AsciiDocカスタム注釈の値のみを含める

AsciiDocを使用してプロジェクトを文書化したいと思います。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を初めて使用しています。このユースケースでは、オフベースになる可能性があります。

出典

2016-10-13 Jordan

あなたの質問は正確には何ですか？問い合わせ方法については、http://stackoverflow.com/help/how-to-askを参照してください。 –

最初は正式な質問をしていませんでしたが、AsciiDocを使用している（REST）APIを文書化する明白な目標は貴重なものであると考えていますので、

Q：一般的な文書コメントにはどのような形式が適していますか？

：Javadoc。プログラミング言語はC++やJavaのように見えます。自動的に抽出可能なコメントの形式の一般的な標準は、JavaDoc形式です。 /** Prefixed API doc */ int foo; /// postfixed API doc Javadocを使用すると、このコンベンション、特に開発環境（IDE）を理解する多くのツールが存在するという利点があります。）。

Q：このようなドキュメントコメントを抽出する既存のプロセッサはありますか？

：Javadoc自体（Javaのみ、私は仮定します）、Doxygen（C言語の言語）、Asciidoclet [1] [2]。 Asciidocletは通常のJavadoc用のプラグインの一種であるDoclet [3]ですが、通常はIDEに統合されています。 Asciidocletは、asciidoc、またはむしろasciidoctorの構文をdocコメントの中で理解します。これらのプロセッサのコンポーネントの一部は、必要に応じて再利用することができます。

Q：REST APIをドキュメント化する際のベストプラクティスとは何でしょうか？

：Swagger（http://swagger.io/）がREST APIのドキュメントとして人気があることがすぐわかります。しかし、それはasciidocを使用しません。

：asciidocマークアップを使用してAPIを文書化するにはどうすればよいですか？

：「asciidocを使用してAPIを文書化する」ネットを検索してください。上のリンクを見てください。あなたは、JavadocとSwaggerとAsciidocとの和解に成功した人もいます。しかし、彼らはAsciidocletを知らなかったようです。

出典

2017-01-27 16:53:43

AsciiDocカスタム注釈の値のみを含める

答えて

関連する問題