Java-ドキュメントコメント

Java言語は3種類のコメントをサポートしています-

シニア番号	コメントと説明
1	*/ text /* コンパイラーは/ から /までのすべてを無視します。
2	//text コンパイラは//から行末までのすべてを無視します。
3	/ documentation /* これはドキュメンテーションコメントであり、一般的には doc comment。ザ・JDK javadocツールは、自動生成されたドキュメントを準備するときにドキュメントコメントを使用します。

この章では、Javadocについて説明します。Javadocを利用してJavaコードの有用なドキュメントを生成する方法を見ていきます。

Javadocとは何ですか？

Javadocは、JDKに付属するツールであり、JavaソースコードからHTML形式のJavaコードドキュメントを生成するために使用されます。これには、事前定義された形式のドキュメントが必要です。

以下は、/ *…。* /内の行がJavaの複数行コメントである簡単な例です。同様に、//の前の行はJavaの単一行コメントです。

例

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

説明部分に必要なHTMLタグを含めることができます。たとえば、次の例では、見出しに<h1> .... </ h1>を使用し、段落区切りの作成に<p>を使用しています-

例

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

javadocタグ

javadocツールは次のタグを認識します-

鬼ごっこ	説明	構文
@著者	クラスの作成者を追加します。	@author name-text
{@コード}	テキストをHTMLマークアップまたはネストされたjavadocタグとして解釈せずに、コードフォントでテキストを表示します。	{@code text}
{@docRoot}	生成されたページから生成されたドキュメントのルートディレクトリへの相対パスを表します。	{@docRoot}
@deprecated	このAPIを使用しないことを示すコメントを追加します。	@deprecated deprecatedtext
@例外	追加します Throws 生成されたドキュメントの小見出しと、クラス名と説明テキスト。	@exceptionクラス名の説明
{@inheritDoc}	からコメントを継承します nearest 継承可能なクラスまたは実装可能なインターフェイス。	直近のスーパークラスからのコメントを継承します。
{@リンク}	指定されたパッケージ、クラス、または参照されたクラスのメンバー名のドキュメントを指す、表示されているテキストラベルを含むインラインリンクを挿入します。	{@link package.class＃member label}
{@linkplain}	リンクのラベルがコードフォントではなくプレーンテキストで表示されることを除いて、{@ link}と同じです。	{@linkplain package.class＃member label}
@param	「パラメーター」セクションに、指定されたパラメーター名の後に指定された説明が続くパラメーターを追加します。	@paramパラメータ名の説明
@return	説明テキストを含む「返品」セクションを追加します。	@returnの説明
@見る	参照を指すリンクまたはテキストエントリを含む「関連項目」の見出しを追加します。	@リファレンスを参照
@シリアル	デフォルトのシリアル化可能なフィールドのドキュメントコメントで使用されます。	@serialフィールドの説明\| 含める\| 除外する
@serialData	writeObject（）またはwriteExternal（）メソッドによって書き込まれたデータを文書化します。	@serialDataデータの説明
@serialField	ObjectStreamFieldコンポーネントを文書化します。	@serialFieldフィールド名フィールドタイプフィールドの説明
@since	生成されたドキュメントに、指定されたsince-textを含む「Since」見出しを追加します。	@リリース以降
@throws	@throwsタグと@exceptionタグは同義語です。	@throwsクラス名の説明
{@値}	静的フィールドのドキュメントコメントで{@value}を使用すると、その定数の値が表示されます。	{@value package.class＃field}
@バージョン	-versionオプションを使用すると、生成されたドキュメントに、指定されたバージョンテキストを含む「バージョン」小見出しが追加されます。	@versionバージョン-テキスト

例

次のプログラムは、ドキュメントのコメントに使用できる重要なタグのいくつかを使用しています。要件に基づいて、他のタグを利用できます。

AddNumクラスに関するドキュメントはHTMLファイルAddNum.htmlで作成されますが、同時にindex.htmlという名前のマスターファイルも作成されます。

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

ここで、javadocユーティリティを使用して上記のAddNum.javaファイルを次のように処理します-

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

生成されたすべてのドキュメントは、ここで確認できます-AddNum。JDK 1.7を使用している場合、javadocは優れたものを生成しませんstylesheet.css、から標準スタイルシートをダウンロードして使用することをお勧めします https://docs.oracle.com/javase/7/docs/api/stylesheet.css