java-docs

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

• public および protected メンバーは Javadoc コメントで文書化する必要があります。
• package-private および private メンバーについても、特に複雑であったり自己説明的でない場合には、文書化することが推奨されます。
• Javadoc コメントの最初の文は要約説明です。メソッドが何を行うかの簡潔な概要とし、ピリオドで終える必要があります。
• メソッドのパラメータには @param を使用します。説明は小文字で始まり、ピリオドで終わりません。
• メソッドの戻り値には @return を使用します。
• メソッドがスローする例外を文書化するには @throws または @exception を使用します。
• 他の型やメンバーへの参照には @see を使用します。
• 基底クラスやインターフェースからドキュメントを継承するには {@inheritDoc} を使用します。
  • ただし、大幅な動作変更がある場合は除きます。その場合は差異を文書化する必要があります。
• ジェネリック型やメソッドの型パラメータには @param <T> を使用します。
• インラインコードスニペットには {@code} を使用します。
• コードブロックには <pre>{@code ... }</pre> を使用します。
• 機能が導入された時期（例: バージョン番号）を示すには @since を使用します。
• メンバーのバージョンを指定するには @version を使用します。
• コードの作成者を指定するには @author を使用します。
• メンバーを非推奨としてマークし、代替手段を提供するには @deprecated を使用します。