ドキュメントには2つのタイプがあります。
1つのタイプImplementation Documentationには、構成の特定の実装に関する情報(クラス、メソッドなど)が含まれています。将来の私、メンテナー、デバッガーなどを対象としています。
そして、提供されたAPIの使用方法に関する情報を含むsage Documentationがあります。特定の実装に関する情報は含まれておらず、APIのユーザーを対象としています。
両方を1つのファイルに含めるにはどうすればよいですか? (または、両方を1つのファイルに含めますか?含まない場合、どのタイプがソースファイルに属しますか?)
Java-docやベストプラクティスを使用した特別なテクニックはありますか?
どちらもソースファイルに関連付けることができます。
実装ドキュメント開発の決定を反映してコードに関連付けられ、関連するコードとともにソースファイル内に入ります。
使用ドキュメント in Javaはjavadoc形式で提供でき、そこからAPIドキュメント(HTMLファイルなど)を抽出できます。実装に関しては理想的には中立ですが、はまだコードに関連付けられているため、IDEを使用して開発し、クラス/メソッドの上にマウスを置くと、APIクラスの使用中に調べることができます。
/** <b>Usage Documentation</b> in javadoc format providing class description and usage. */
public class PublicClass {
/** <b>Usage Documentation</b> in javadoc format providing method description and usage.
* @param aParameter parameter description.
* @return either the operation succeeded or not.
* @throws SomeException if an exception occurred.
*/
public boolean publicMethodThatBelongsToTheAPI(int aParameter) throws SomeException {
/* Implementation Documentation (non-javadoc) */
doSomething();
(...)
}
private void doSomething() {
// More implementation documentation
(...)
}
}