javadoc - javadoc コメントのコード例

Question

複数のプログラマーが javadocs の例に貢献しており、一部の例には次のようにフォーマットされたコメントが含まれています。

/*
 *
 */

これらの例を javadoc コメントに入れると、例のコメントを閉じて javadoc コメントを閉じます。

/**
 *
 * /*
 *  *
 *  */  <-- right here
 *
 */

この形式でコメントを書くことができないことを全員に言わずに、これを処理する適切な方法はありますか?

Answer 1

Javadocコメントはhtmlを使用するため、/をエンティティとしてエンコードします。/

/**
 *
 * /*
 *  *
 *  *&#47;  <-- right here
 *
 */

コード例にそのようなコメントを入れないように全員に伝える方が簡単かもしれません。

Answer 2

私の意見では、コードが自明ではないか、少なくとも簡単な説明で理解できるほど単純でない場合は、コードをリファクタリングする必要があります。短くするか、変数をより理解しやすくするか、ロジックを再考する必要があります。

いずれにせよ、私はそれを回避する方法があるとは思いません。例を含めたい場合は、その例の中にコメントを入れないでください。本当にコメントが必要な場合は、//表記を使用してください。

Answer 3

コメントしたソースコードをコメントに入れたいのはなぜですか？

そのようなことが必要な場合、これはあなたのデザインに何か問題があるように聞こえます。

Answer 4

HTMLはJavadocコメント内で許可されています。<code>または<pre>要素内のコメントでコードを囲みます。例えば：

/**
 * Outputs "Hello World" to the console.
 *
 * <code>System.out.println("Hello World");</code>
 */

Answer 5

「/**/」コメントはネストできません。「//」コメントは可能ですが、最初の行の終わりまでしか効果がありません。

一般的に言って、JavaDocsに実際のコードを含めるのは良いことではありません。1つには、より抽象的なものにする必要があります（「方法」ではなく「理由」）。