Java何らかの方法でソースファイルにマッピングされた別個のdocsファイルのコードドキュメント？
インラインJavaのドキュメントに代わる優れた方法は何ですか。つまり、別のドキュメントファイルを何らかの方法でJavaソースファイルにマッピングできますか？
私はコードに散らばった巨大なコメントセクションが好きではありませんでした。
私は パッケージコメント のJavadoc機能を使用して、詳細なドキュメントコメントでソースコードをポイ捨てしないようにしています。
パッケージレベルのコメント
Javadoc 1.2では、パッケージレベルのドキュメントコメントを利用できます。各パッケージは、Javadocツールが生成するドキュメントにマージする独自のパッケージレベルのドキュメントコメントソースファイルを持つことができます。このファイルの名前は
package.htmlです（すべてのパッケージで同じ名前です）。このファイルは、すべての*.Javaファイルとともにソースディレクトリに保持されます。 （packages.htmlファイルを新しいdoc-filesソースディレクトリに配置しないでください。これらのファイルは宛先にコピーされるだけで、処理されません。）ファイル package.html は
Java.textのパッケージレベルのソースファイルの例であり、 package-summary.html はJavadocツールが生成するファイルです。Javadocツールは、3つのことを実行して
package.htmlを処理します...
上記の機能を使用して、専用の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が存在する場合は、javadocおよびその他の同様のドキュメント生成システムのpackage.htmlの代わりに使用することをお勧めします。このファイルが存在する場合、ドキュメント生成ツールは、package-info.Javaの（注釈が付けられている可能性がある）パッケージ宣言の直前にあるパッケージドキュメントコメントを探す必要があります。このようにして、package-info.Javaは、パッケージレベルの注釈とドキュメントの唯一のリポジトリになります。将来、他のパッケージレベルの情報を追加することが必要になった場合、このファイルはこの情報の便利なホームとなるはずです。