java-docs

Java ドキュメント（Javadoc）のベストプラクティス

原則

• コードが実際に行うことだけをドキュメント化します。まず実装、呼び出し元、テストを確認してください。検証していない動作、しきい値、スレッドセーフ性、null 許容性、例外を決して作り上げないでください。確信が持てない場合は記載しないか、確認してください。
• プロジェクトの既存のドキュメントスタイル（言語、タグの順序、コメント形式 /** */ と ///）に従います。ユーザーから依頼がない限り、既存のコメントを書き換えたり、コードベース全体に一括でドキュメントを追加したりしないでください。変更は依頼された範囲に限定します。
• 新しい機能を使う前に JDK のバージョン（maven.compiler.release、ツールチェーン、java -version）を確認し、その範囲内で使用してください。

規約

• @since は API が導入された実際のバージョンに限って使用します。@deprecated は理由と代替手段を記載し、@Deprecated と併用します。
• @author と @version は、プロジェクトですでに使用されている場合に限って使用します。
• コードブロックは、JDK のバージョンに応じて使い分けます。
  • すべての JDK：<pre>{@code ... }</pre>（行頭の @ はエスケープし、波括弧の対応を取ります）。
  • JDK 18 以降：インラインコードには {@snippet : ... }、または snippet-files/ 内のファイルを指定した {@snippet file="Example.java" region="demo"} を使用します（例にはこちらを推奨します。javadoc はスニペットのソースをコンパイルも検証もしないため、その保証が必要な場合は、別のビルド／テスト用ソースセットでファイルをコンパイルしてテストしてください）。必要に応じて // @highlight substring="x" や // @replace のマークアップを使用します。
  • JDK 23 以降のみ（JEP 467）：/// を使った Markdown 形式のドキュメントコメントを使用し、リンクには [Type#member]、コードブロックにはフェンスを使用します。プロジェクトがすでに使用している場合、またはユーザーから依頼された場合に限り、JDK 23 以降の javadoc でビルドする場合に使用してください。

検証

• mvn -q javadoc:javadoc（または ./gradlew javadoc）を実行します。単一ファイルの場合は javadoc -Xdoclint:all -d target/javadoc-check <files> を実行します。追加した警告やエラー（不足している @param、不正な HTML、解決できない {@link}、未知のタグ）をすべて修正します。
• ドキュメント化した内容と実行したコマンドを報告します。コードから検証できなかった主張があれば明記します。