Javadoc

‹テンプレート マニュアルは統合が検討されています。› 

Javadocは、 Java言語（現在はOracle Corporationが所有）用にSun Microsystemsが作成したドキュメントジェネレーターであり、 JavaソースコードからHTML形式のAPIドキュメントを生成します。HTML形式は、関連するドキュメントをハイパーリンクできる利便性を追加するために使用されます。^[1]

Javadoc で使用される「doc コメント」形式^{[2] は}、Java クラスを文書化するための事実上の業界標準です。IntelliJ IDEA、NetBeans、Eclipseなどの一部のIDE ^[3]は、Javadoc テンプレートを自動的に生成します。多くのファイル エディターは、ユーザーによる Javadoc ソースの作成を支援し、Javadoc 情報をプログラマーの内部参照として使用します。

Javadoc は、ドックレットとタグレットを作成するための API も提供しており、ユーザーはこれを使用して Java アプリケーションの構造を分析できます。これにより、JDiff は 2 つのバージョンの API 間で何が変更されたかを示すレポートを生成できます。

Javadoc は、コンパイル時にすべてのコメントが削除されるため、Java のパフォーマンスには影響しません。コメントと Javadoc を記述すると、コードをよりよく理解し、より適切に保守できるようになります。

Javadocは初期のJava言語ドキュメントジェネレータでした。^[4]ドキュメントジェネレータが使用される前は、通常はソフトウェアのスタンドアロンドキュメントのみを作成するテクニカルライターを使用するのが一般的でしたが、^[5]このドキュメントをソフトウェア自体と同期させることは非常に困難でした。

Javadoc は Java の最初のリリース以来使用されており、通常はJava Development Kitの新しいリリースごとに更新されます。

Javadoc の構文@fieldは、クロスランゲージのDoxygen、 JavaScript のJSDocシステム、 Erlangの EDoc 、Apple のHeaderDocなど、他の言語のドキュメント システムによってエミュレートされています。

/*Javadoc コメントは、標準の複数行コメント タグとによってコードから区切られます*/。開始タグ (コメント開始区切り文字と呼ばれる) には、 のように追加のアスタリスクが付きます/**。

1. 最初の段落は、文書化された方法の説明です。
2. 説明の後に、次のことを示すさまざまな数の説明タグが続きます。
   1. メソッドのパラメータ（@param）
   2. メソッドが返すもの（@return）
   3. メソッドがスローする可能性のある例外（@throws）
   4. @seeその他のあまり一般的ではないタグ（「参照」タグなど）

ほとんどの Javadoc コメントはタグ内に埋め込まれます /** ... */。Javadoc コメント ブロックは、改行なしで項目のすぐ上に配置され、インポート ステートメントの下に配置されます。クラス宣言には通常、次の内容が含まれます。

// インポート文

/** 
* @author Firstname Lastname <address @ example.com> 
* @version 1.6 (プログラムの現在のバージョン番号) 
* @since 1.2 (このクラスが最初に追加されたパッケージのバージョン) 
*/ 
public class Test { // クラス本体}   
    

メソッドのドキュメント コメントには通常、項目の機能を説明する短く簡潔な 1 行の説明が含まれ、その後に長い説明が続き、最後にメソッドの受け入れられる入力引数と戻り値をリストするタグ セクションが含まれます。Javadoc は HTML として扱われるため、<p>複数の段落を示すには " " 段落区切りタグを使用できます。

/** 
* 1 行で短い説明。(1) 
* <p> 
* 長い説明。もしあるとしたら、(2) 
* ここです。
* <p> * さらに、 
HTML 段落区切りで区切られた連続した段落で、さらに説明が続きます。 
* * @param variable 説明テキスト テキスト テキスト。(3) * @return 説明テキスト テキスト テキスト。*/ public int methodName (...) { // return ステートメントを含むメソッド本体}




    
    

変数はメソッドと同様に文書化されますが、コメントの最後にタグが付いていないことがよくあります。

/** 
* ここで変数の説明。
*/ 
private int debug = 0 ;    

1つのドキュメンテーションコメントで複数の変数を定義することは推奨されません^{[6]。Javadoc}は各変数を読み取り、生成されたHTMLページにそれらを個別に配置します。その際、すべてのフィールドにコピーされる同じドキュメンテーションコメントが使用されます。

/** 
* 点 (x,y) の水平および垂直距離
*/ 
public int x , y ; // 避けるべき         

代わりに、各変数を個別に記述して文書化することをお勧めします。

/** 
* 点の水平距離。
*/ 
public int x ;  

/** 
* 点の垂直距離。
*/ 
public int y ;  

利用可能なJavadocタグ^[7]の一部を以下の表に示します。

メソッドを文書化する Javadoc の例を次に示します。この例では、スペースと文字数が^{[明確化が必要]}の規則に従っていることに注意してください。

/** 
* チェスの動きを検証します。
* 
* <p>駒を動かすには、{@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} を使用します。
* 
* @param fromFile 駒の移動元のファイル
* @param fromRank 駒の移動元のランク
* @param toFile 駒の移動先のファイル
* @param toRank 駒の移動先のランク
* @return 動きが有効な場合は true、それ以外の場合は false 
* @since 1.0 
*/ 
boolean isValidMove ( int fromFile , int fromRank , int toFile , int toRank ) { // ...body }         
    


/** 
* チェスの駒を動かします。
* 
* @see java.math.RoundingMode 
*/ 
void doMove ( int fromFile , int fromRank , int toFile , int toRank ) { // ...body }          
    

DocletプログラムはJavadocツールと連携してJavaで書かれたコードからドキュメントを生成します。^[8]

ドックレットは Java プログラミング言語で記述されており、Doclet API次の目的で使用されます。

• ドキュメントに含めるコンテンツを選択する
• コンテンツのプレゼンテーションをフォーマットする
• ドキュメントを含むファイルを作成する

JavadocStandardDocletに含まれる[1]は、フレームベースのHTMLファイルとしてAPIドキュメントを生成します。多くの非標準のドックレットがWeb上で利用可能であり^[要出典]、多くの場合は無料で利用できます。これらは次の目的で使用できます。

• API以外のタイプのドキュメントを作成する
• ドキュメントをPDFなどのHTML以外のファイル形式に出力する
• 検索などの追加機能やJavaクラスから生成されたUMLダイアグラムを埋め込んだHTMLとしてドキュメントを出力します。

• ドキュメント生成ツールの比較
• .NET XML ドキュメントのコメント

• Java プラットフォーム、Standard Edition Javadoc ガイド
• JSR 260 Javadoc タグ テクノロジ更新Java 仕様要求(新しい Javadoc タグを定義)
• ashkelon で Javadoc を改良する
• さまざまな Java ドキュメントを Windows ヘルプ形式に変換しました