AsciiDoc 仅包含自定义注释中的值答案

【问题标题】：AsciiDoc Include only values from custom annotationAsciiDoc 仅包含自定义注释中的值
【发布时间】：2016-10-13 19:52:40
【问题描述】：

我想用 AsciiDoc 记录我的项目。

我有一个像下面这样的类，它有 cmets，概述了有关方法中正在处理的步骤的一些细节。我想让这些 cmets 成为我的 .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 的新手，可能对这个用例不太了解。

【问题讨论】：

您的问题到底是什么？询问方式见stackoverflow.com/help/how-to-ask。

标签： asciidoc

【解决方案1】：

尽管最初您没有提出正式问题，但我相信使用 AsciiDoc 记录 (REST) API 的明显目标是崇高的，因此对于您的潜在问题，我将尝试为您指出有希望的方向：

问：一般来说，什么是适合文档 cmets 的格式？

A：Javadoc。您的编程语言看起来像 C++ 或 Java。自动可提取 cmets 格式的流行标准是 JavaDoc 格式。以两个星号开头的前缀 cmets 和以三个而不是两个斜杠开头的行尾 cmets 用于文档生成器：/** Prefixed API doc */ int foo; /// postfixed API doc 使用 Javadoc 的优势在于，有许多现有工具可以理解这种约定，尤其是开发环境 (IDE)。

问：是否存在提取此类文档 cmets 的现有处理器？

A：Javadoc 本身（我认为仅限 Java）、Doxygen（类 C 语言）、Asciidoclet[1][2]。 Asciidoclet 是一个 Doclet[3]，它是一种用于常规 Javadoc 的插件，通常以某种方式集成到您的 IDE 中。 Asciidoclet 理解 doc cmets 内部的 asciidoc，或者更确切地说是 asciidoctor 语法。您或许可以根据自己的需要重新调整这些处理器组件的用途。

问：记录 REST API 的最佳实践是什么？

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

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

A：在网上搜索“使用 asciidoc 记录 API”。查看顶部链接。您会发现有些人在协调 Javadoc 与 Swagger 和 Asciidoc 方面取得了一些成功。但是，在我看来，他们并不知道 Asciidoclet。

【讨论】：

自创建此答案以来，有一个工具 github.com/verhas/jamal 您可以将其列为工具来回答“是否存在提取此类文档 cmets 的现有处理器？” Jamal 用途相当广泛，与列出的工具相比，几乎可以用于任何编程语言。