翻訳: Javadoc コメントでの Markdown 構文の使用

Javadoc コメントでの Markdown 構文の使用

この投稿では、標準の Javadoc 構文の代わりにMarkdown を使用して Javadoc コメントを記述する方法を見ていきます 。では、マークダウンとは何でしょうか? Markdown は、同じ名前のツールを使用してオプションで HTML に翻訳できる単純なマークアップ言語です。Markdown は、Readme ファイルの書式設定、フォーラムへの投稿の作成、およびテキスト エディターで美しいテキスト ドキュメントをすばやく作成するために広く使用されています。(Wikipedia: Markdown ) Markdown でフォーマットされたテキストは非常に読みやすいです。Stack Overflow または GitHub では、ユーザーが生成したコンテンツをフォーマットするために、さまざまな種類の Markdown が使用されています。

インストール

デフォルトでは、Javadoc ツールは Javadoc コメントを使用して API ドキュメントを HTML として生成します。このプロセスは、ドックレットを使用して再構成できます。ドックレットは、Javadoc ツールの出力ファイルの内容と形式を指定する Java プログラムです。 Markdown-doclet は 標準の Java Doclet を置き換えるため、開発者は Javadoc コメントで Markdown 構文を使用できるようになります。maven-javadoc-pluginを使用して Maven にインストールできます。 maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Markdownでコメントを書く

Markdown 構文を使用して Javadoc コメントを記述できるようになりました: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } 実行後

mvn javadoc:Javadoc

生成された HTML API ドキュメントは次の場所にあります。

ターゲット/サイト/APIDOC。

上記のコードに対して生成されたドキュメントは次のようになります。 図からわかるように、Javadoc コメントは完全に HTML に変換されています。

結論

Markdown には、標準の Javadoc 構文に比べて明らかな利点があります。つまり、ソース コードを読みやすくなります。java.util.Map のメソッド コメントの一部を見てください。コメントの多くは書式設定タグでいっぱいで、追加のツールを使用しないと読むのが困難です。ただし、標準の Javadoc 構文でのみ動作するツールや IDE では、Markdown が問題を引き起こす可能性があることに注意してください。出典: mscharhag ブログ「Programming and Stuff」のJCG パートナーMichael ScharhagによるJavadoc コメントでの Markdown 構文の使用。