どういうわけかソースファイルにマップされた別のdocsファイルのJavaコードドキュメント？

インラインJavaドキュメントに代わる優れた方法は何でしょうか。つまり、Javaソースファイルに何らかの方法でマップされた個別のドキュメントファイルを持つことができますか？

私はコードに散らばっている巨大なコメントセクションが好きではありません。

詳細なドキュメントコメントでソースコードをポイ捨てしないように、パッケージコメントの Javadoc機能を使用しています。

パッケージレベルのコメント

Javadoc 1.2では、パッケージレベルのドキュメントコメントを使用できます。各パッケージは、Javadocツールが生成するドキュメントにマージする独自のパッケージレベルのドキュメントコメントソースファイルを持つことができます。このファイルには名前が付けられていますpackage.html（すべてのパッケージで同じ名前です）。このファイルは、すべての*.javaファイルとともにソースディレクトリに保存されます。（packages.htmlこれらのファイルは宛先にのみコピーされ、処理されないため、新しいdoc-filesソースディレクトリにファイルを配置しないでください。）

ファイルのpackage.htmlは用のパッケージレベルのソース・ファイルの一例であるjava.textとパッケージsummary.htmlに Javadocツールが生成するファイルです。

Javadocツールはpackage.html3つのことを実行して処理します...

上記の機能を使用して、パッケージ内のクラスとメソッドの詳細なドキュメントをコードとは別に専用のhtmlファイルに保存しました。JavaファイルのJavadocコメントに関しては、私はそこに簡単な説明を書いて、次のようなテキストを追加しました

詳細については、必要に応じてパッケージのドキュメントを参照してください。

私がこれについて特に気に入った点の1つは、ドキュメントが別のファイルにあり、大きなドキュメント（html）にはより便利な形式ですが、関連するソースコードの近くに保存され、その中のすべての更新が自動的に取得されることです。ビルド。

始まったJava 1.5、あなたは、代わりに置くことができpackage-info.java、パッケージのクラスと一緒に。このファイルは次のようになります。

/**
 * Javadoc for your package here
 */
package com.yourpackage;

JLSのドキュメントでは、これが推奨される方法であると示唆されています。

ファイルシステムベースの実装では、次のスキームを強くお勧めします。唯一の注釈付きパッケージ宣言が存在する場合はpackage-info.java、パッケージのソースファイルを含むディレクトリにあるソースファイルに配置されます...

package-info.javaが存在する場合はpackage.html、javadocおよびその他の同様のドキュメント生成システムの代わりに使用することをお勧めします。このファイルが存在する場合、ドキュメント生成ツールは、package-info.javaの（注釈が付けられている可能性がある）パッケージ宣言の直前にあるパッケージドキュメントコメントを探す必要があります。このようにして、package-info.javaはパッケージレベルの注釈とドキュメントの唯一のリポジトリになります。将来、他のパッケージレベルの情報を追加することが必要になった場合、このファイルはこの情報の便利なホームとなるはずです。