AsciiDoc 仅包含来自自定义注释的值

Question

我想使用 AsciiDoc 记录我的项目。

我有一个像下面这样的 class，它的注释概述了方法中正在处理的步骤的一些细节。我想将这些评论作为我的 .adoc 某些部分的内容。

public RequestResponse processRequest(UserRequest request){
   /* First retrieve info from db calling the stored procedure
      dbo.StoredProcedure with input parameters A,B,C */
   DbResponse dbResponse = dao.getResponse(request);

   // Call method to calculate all scenarios for the Example request
   CalcResult calcResult = util.calculateStuff(request.getAmountList());

   /* Format the response to include the fields from the calcResult as well
      as the request details returned from the DB result set */
   return util.formatResponse(dbResponse,calcResult );
}

最终，该文档将用于向其他开发人员提供有关某些 REST 调用如何处理的概述，而无需他们进入源代码并查看所有步骤。

我是 AsciiDoc 的新手，可能不太了解这个用例。

Answer 1

即使最初您没有提出正式问题，我相信使用 AsciiDoc 记录 (REST) API 的明显目标是崇高的，因此对于您的潜在问题，我会尝试指出你在有前途的方向：

Q: 一般情况下，文档注释的合适格式是什么？

A: Java文档。您的编程语言看起来像 C++ 或 Java。 JavaDoc 格式是自动提取评论格式的流行标准。以两个星号开头的前缀注释和以三个而不是两个斜杠开头的 line-end 注释用于文档生成器：/** Prefixed API doc */ int foo; /// postfixed API doc 使用 Javadoc 的好处是有许多现有工具可以理解此约定，特别是开发环境 (IDEs)。

问: 是否存在提取此类文档注释的现有处理器？

A：Javadoc 本身（我假设只有 Java），Doxygen（C-Like 语言），Asciidoclet[1] [2]. Asciidoclet 是一个 Doclet[3]，它是常规 Javadoc 的一种插件，它通常以某种方式集成到您的 IDE 中。 Asciidoclet 理解文档注释中的 asciidoc，或者更确切地说是 asciidoctor 语法。您可以根据需要重新调整其中一些处理器组件的用途。

Q：记录 REST APIs 时什么被认为是最佳实践？

A：您很快就会发现 Swagger (http://swagger.io/) 在 REST API 文档中很受欢迎。但是它不使用asciidoc。

问：如何使用 asciidoc 标记来记录我的 API？

A: 在网上搜索"using asciidoc to document APIs"。查看顶部链接。您会发现有些人在协调 Javadoc 与 Swagger 和 Asciidoc 方面取得了一些成功。然而，在我看来，他们并不知道 Asciidoclet。

AsciiDoc 仅包含来自自定义注释的值

AsciiDoc Include only values from custom annotation

asciidoc