1. 概要

このチュートリアルでは、Javadocコメントをフォーマットするさまざまな方法について説明します。 ドキュメントのコメントとして記述されたコードスニペットのフォーマットの分析に焦点を当てます。

2. 序章

Javadocは、Javaクラスのドキュメントを生成するためのツールです。 Javaソースファイルで指定されたドキュメントコメントを処理し、対応するHTMLページを生成します。 

Javadocドキュメントの詳細については、記事を参照してください。

3. スニペットをJavadocコメントとしてコーディングする

Javaクラスのドキュメントコメントの一部としてコードスニペットを含めることができます。 生成されたHTMLページに正しいインデントと文字を含むコードスニペットを表示したいと思います。

コメントの一部としてJavaコードスニペットを追加してみましょう。

/**
* This is an example to show default behavior of code snippet formatting in Javadocs
* 
* public class Application(){
* 
* }
* 
*/

対応するHTMLページ：

デフォルトでは、改行とスペースはJavadocコメントに保持されません。 これにより、特に複数行のコードスニペットの場合、不適切なインデントが発生します。

コメントで正しいインデントを維持する方法を見つけましょう。

3.1. を使用して



鬼ごっこ


HTMLは




事前にフォーマットされたテキストを示すタグ。 囲まれたテキストのスペースと改行を保持します。これにより、コードスニペットに必要なインデントが保持されます。


/**
* This is an example to show usage of HTML pre tag while code snippet formatting in Javadocs
* 
* <pre>
* public class Application(){
*     List<Integer> nums = new ArrayList<>();
* }
* 
* </pre>
*/


対応するHTMLページ：




ここでは、コードスニペットに必要なスペースと改行を正常に保持しています。 ただし、現在、別の問題が発生しています。Genericsが表示されません。コードスニペットの一部として入力されました。


コメントがHTMLページに解析されると、 コードスニペットの一部がHTMLタグとして誤って解釈される可能性があります 、 お気に入り上記の例では。 


コメント内に埋め込まれたHTML文字の正しいフォーマットを維持する方法を探りましょう。


3.2. HTML文字エンティティの使用


コードスニペットに’のようなHTML予約文字が含まれている場合 < ‘、’ >> ‘ また ‘ ＆ ‘、コメントを解析している間、これらはHTML文字として解釈できます。 これらの文字を保持するために、必要な文字の代わりに文字エンティティを使用できます。 


たとえば、<を使用して’を表すことができます < ‘ キャラクター：


/**
* This is an example to show usage of HTML character entities while code snippet formatting in Javadocs
* 
* <pre>
* public class Application(){
*     List<Integer> nums = new ArrayList<>();
* }
* 
* </pre>
*/


対応するHTMLページ：




3.3. @codeタグの使用


J avadocは@codeタグを提供します。これは、角かっこ内に埋め込まれたコメントをHTML文字ではなくソースコードとして扱います。 これにより、Characterエンティティを使用してHTML予約文字をエスケープせずに、直接使用できます。


/**
* This is an example to show usage of javadoc code tag while code snippet formatting in Javadocs
* 
* <pre>
* 
* public class Application(){
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/


対応するHTMLページ：




 @codeタグは、コメントに含まれるインデントの問題に対応していないことに注意してください。 このために、私たちは使用する必要があります




さらにタグを付けます。


上で見たように、Javadocは「@」文字を使用してタグを識別します。 コードスニペットの一部として「@」がある場合、Javadocによって誤って解釈され、コメントのレンダリングが正しくなくなります。 


例を使用してこれを見てみましょう：


/**
* This is an example to show issue faced while using annotations in Javadocs
* 
* <pre>
* 
* public class Application(){
*            @Getter
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/


対応するHTMLページ：




 


ご覧のとおり、Javadocは @Getter をタグとして処理し、コメントは正しくレンダリングされません。 Javadocが提供する@codeタグ内に注釈（または@文字を使用したコード）を埋め込むことができます。


/**
* This is an example to show usage of javadoc code tag for handling '@' character
* 
* <pre>
* 
* public class Application(){
*     {@code @Getter}
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/


対応するHTMLページ：




3.4. @literalタグを使用する


@literalタグを使用しても、同様の動作を実現できます。 @codeタグと@literalタグの唯一の違いは、@codeタグが囲まれたテキストをコードフォントでフォーマットすることです。


/**
* This is an example to show difference in javadoc literal and code tag
* 
* <p>
* 
* {@literal @Getter}
* {@literal List<Integer> nums = new ArrayList<>(); }
*   
* <br />
* {@code @Getter}
* {@code List<Integer> nums = new ArrayList<>(); }
* </p>
*/


対応するHTMLページ：




したがって、コードスニペットがHTMLページに正しくレンダリングされました。


3.5. jQueryコードスニペットのフォーマット


ここでは、Javaコードスニペットの例を取り上げました。 同じ機能が他の言語にも適用できます。 


ドキュメントのコメントとして、簡単なjQueryコードスニペットを含めましょう。


/**
* This is an example to illustrate a basic jQuery code snippet embedded in documentation comments
* <pre>
* {@code <script>}
* $document.ready(function(){
*     console.log("Hello World!);
* })
* {@code </script>}
* </pre>
*/


対応するHTMLページ：




3.6. HTMLコードスニペットのフォーマット


これまでのところ、Javadocを使用するとコメントの書式設定にHTMLタグを使用できる一方で、マークアップなしでHTML文字を使用する場合に問題が発生する可能性があることを認識しています。 


たとえば、コメントにHTMLコードスニペットを挿入したい場合があります。


ドキュメントコメントの一部としてHTMLコードスニペットを挿入し、それがどのように動作するかを見てみましょう。


/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>
* </pre>
* 
*/


対応するHTMLページ：




ここでは、コメント内に埋め込まれたコードスニペットがHTMLマークアップを使用してHTMLページに解析されていることがわかります。 上記のように、@codeタグを使用して問題を修正できます。


/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>{@code
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>}
* </pre>
* 
*/


対応するHTMLページ：




4. 結論


Javadocコメントをフォーマットするさまざまな方法を検討しました。 適切にフォーマットされたドキュメントを生成するための要件に従って、フォーマットオプションを選択できます。 


HTMLタグを使用して、Javadocコメントのフォーマットを強化したり、要件に合うときはいつでもそれらをエスケープしたりできます。