web-dev-qa-db-ja.com

実装と使用に関するドキュメントを1つのファイルに含めるにはどうすればよいですか

ドキュメントには2つのタイプがあります。

1つのタイプImplementation Documentationには、構成の特定の実装に関する情報（クラス、メソッドなど）が含まれています。将来の私、メンテナー、デバッガーなどを対象としています。

そして、提供されたAPIの使用方法に関する情報を含むsage Documentationがあります。特定の実装に関する情報は含まれておらず、APIのユーザーを対象としています。

両方を1つのファイルに含めるにはどうすればよいですか？ （または、両方を1つのファイルに含めますか？含まない場合、どのタイプがソースファイルに属しますか？）

Java-docやベストプラクティスを使用した特別なテクニックはありますか？

documentationjavadocs
1
Angelo.Hannes

どちらもソースファイルに関連付けることができます。

実装ドキュメント開発の決定を反映してコードに関連付けられ、関連するコードとともにソースファイル内に入ります。

使用ドキュメント 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
        (...)
    }
}
1
Piovezan