Java Language => Javaコードの文書化

前書き

Javaコードのドキュメントは、 javadocを使用して生成されることがよくあります。 Javadocは、JavaソースコードからHTML形式のAPIドキュメントを生成する目的で、Sun Microsystemsによって作成されました。 HTML形式を使用すると、関連する文書を一緒にハイパーリンクすることができるという利便性が得られます。

構文

/ ** - クラス、フィールド、メソッド、またはパッケージ上のJavaDocの開始
@author //クラス、インタフェースまたはenumの作成者に名前を付ける。それは必須です。
@version //そのクラス、インタフェース、またはenumのバージョン。それは必須です。ソース管理ソフトウェアがチェックアウト時に記入するために、％I％や％G％のようなマクロを使用することができます。
@param //メソッドまたはコンストラクタの引数（パラメータ）を表示する。パラメータごとに@paramタグを1つ指定します。
@return // void以外のメソッドの戻り値の型を表示します。
@exception //メソッドやコンストラクタからスローされる例外を表示します。捕捉されなければならない例外は、ここにリストされていなければなりません 。必要に応じて、ArrayIndexOutOfBoundsExceptionのように、キャッチする必要のないものも含めることができます。スローできる例外ごとに1つの@exceptionを指定します。
@throws // @exceptionと同じです。
@see //メソッド、フィールド、クラス、またはパッケージにリンクします。 package.Class＃何かの形で使用してください。
@since //このメソッド、フィールド、またはクラスが追加されたとき。たとえば、 java.util.Optional <T>のようなクラスのJDK-8です。
@serial、@serialField、@serialData // serialVersionUIDを表示するために使用します。
@deprecated //クラス、メソッド、またはフィールドを廃止予定としてマークする。たとえば、 java.io.StringBufferInputStreamがあります。既存の廃止予定クラスの完全なリストはこちらをご覧ください。
{@link} // @seeと似ていますが、カスタムテキストで使うことができます：{@link #setDefaultCloseOperation（int closeOperation）}詳細については、JFrame＃setDefaultCloseOperationを参照してください。
{@linkplain} //コードフォントがなく、{@link}と似ています。
{@code} // HTMLタグなどのリテラルコード。例：{@code <html> </ html>}。しかし、これはモノスペースフォントを使用します。モノスペースフォントなしで同じ結果を得るには、{@literal}を使用してください。
{@literal} //モノスペースのフォントを使わずに{@code}と同じです。
{@value} //静的フィールドの値を表示します。JFrame＃EXIT_ON_CLOSEの値は{@value}です。または、特定のフィールドにリンクすることができます：アプリ名{@value AppConstants＃APP_NAME}を使用します。
{@docRoot} //現在のファイルを基準にしたJavaDoc HTMLのルートフォルダ。例：<a href="{@docRoot}/credits.html">クレジット</a>
HTMLは許可されています：<code> "Hi cookies" .substring（3）</ code>。
* / - JavaDoc宣言の終わり

備考

Javadocは、コード内のコメントをHTMLドキュメントに変換できるJDKに含まれているツールです。 Java API仕様は、Javadocを使用して生成されました。サードパーティのライブラリの多くのドキュメントでも同じことが言えます。

クラス文書

すべてのJavadocコメントは、ブロックコメントとアスタリスク（ /** ）で始まり、ブロックコメントが（ */ ）のときに終了します。任意で、各行は任意の空白とアスタリスクで始めることができます。ドキュメンテーション・ファイルが生成されると、これらは無視されます。

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

EnumsとInterfacesにも、 Classes使用されているのと同じタグと書式を使用できます。

メソッドドキュメント

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

フィールド文書

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

パッケージドキュメント

Java SE 5

と呼ばれるファイル使用のJavadocにパッケージレベルのドキュメントを作成することが可能であるpackage-info.java 。このファイルは以下のようにフォーマットする必要があります。先行する空白とアスタリスク（省略可能）。通常、書式設定の理由により各行に表示されます。

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

上記の場合、このファイルpackage-info.javaをJavaパッケージcom.example.fooフォルダの中に置く必要があります。

リンク

他のJavadocへのリンクは@linkタグで行い@link ：

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

@seeタグでは、 See alsoセクションに要素を追加できます。 @paramや@returnと同様に、表示される場所は関係ありません。仕様では、 @return後に記述する必要があります。

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

外部リソースへのリンクを追加する場合は、HTMLの<a>タグを使用します。どこでもインラインで使うことも、 @link @seeタグと@seeタグの両方で使うこともできます。

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

コマンドラインからのJavadocsのビルド

多くのIDEはJavadocから自動的にHTMLを生成するためのサポートを提供します。いくつかのビルドツール（ MavenやGradleなど）には、HTML作成を処理できるプラグインもあります。

ただし、これらのツールはJavadoc HTMLを生成する必要はありません。これは、コマンドラインjavadocツールを使用して行うことができます。

このツールの最も基本的な使い方は次のとおりです。

javadoc JavaFile.java

JavaFile.javaのJavadocコメントからHTMLを生成します。

[source-directory]にあるすべてのJavaファイルを再帰的に読み込むコマンドラインツールを実際に使用すると、 [package.name]とすべてのサブパッケージのドキュメントが作成され、生成されたHTMLが[docs-directory]次のとおりです。

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

インラインコードのドキュメント

Javadocのドキュメントコード以外にも、コードはインラインで文書化できます。

単一行のコメントは、 //によって開始され、同じ行にある文の後に置かれますが、前には置かれません。

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

複数行コメントは/*と*/間に定義されます。それらは複数の行にまたがることができ、文の間に置かれることさえあります。

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocsは、 /**で始まる特別な形式の複数行コメントです。

あまりにも多くのインラインコメントはコードの可読性を低下させる可能性があるため、コードが十分に自明ではない場合や、設計上の決定が明らかでない場合はまばらに使用する必要があります。

1行コメントの使用例としては、TAGを使用することがあります。短くてコンベンションドリブンなキーワードです。いくつかの開発環境では、そのような単一コメントのための特定の規則を認識しています。一般的な例は

//TODO
//FIXME

または、Jiraのために参照を発行する

//PRJ-1234

ドキュメント内のコードスニペット

ドキュメントの中にコードを書く標準的な方法は、 {@code }構造です。 <pre></pre>中に複数行のコードラップがある場合。

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

場合によっては、javadocコメントの中に複雑なコードを入れる必要があるかもしれません。 @記号は特に問題があります。古い<code>タグを{@literal }構造体と共に使用することで、この問題は解決されます。

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

ライセンスを受けた CC BY-SA 3.0

所属していない Stack Overflow

Java Language
Javaコードの文書化

サーチ…

前書き

構文

備考