Question

我想用AsciiDoc记录我的项目。

我有一个类似下面的类，其中包含一些注释，这些注释概述了有关方法中正在处理的步骤的一些细节。我想将这些评论作为我的.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的明显目标是高尚的，因此对于您的潜在问题，我会尝试指出您有前途的方向：

问：一般来说，文档评论的格式是什么？

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

问：现有处理器是否提取了此类文档注释？

A ：Javadoc本身（我只假设Java），Doxygen（C-Like语言），Asciidoclet [1] [2]。 Asciidoclet是一个Doclet [3]，它是常规Javadoc的插件，它通常以某种方式集成到您的IDE中。 Asciidoclet在doc评论中理解asciidoc，或者说asciidoctor语法。您可能可以重新利用其中一些处理器＆＃39;满足您需求的组件。

问：记录REST API时，最佳做法是什么？

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

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

A ：在网上搜索＆＃34;使用asciidoc来记录API＆＃34;。看看顶部的链接。您会发现有些人在使用Swagger和Asciidoc协调Javadoc方面取得了一些成功。然而，在我看来，他们并不知道Asciidoclet。

AsciiDoc仅包含自定义注释

1 个答案: