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 を使用してください。