Java-documentation

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

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

Sr.No.	Comment & Description
1	/*text/* コンパイラは、/*から */までのすべてを無視します。
2	//text コンパイラは//から行末までのすべてを無視します。
3	/ documentation/* これはドキュメンテーションコメントであり、一般的には* docコメント*と呼ばれます。 JDK javadoc ツールは、自動生成されたドキュメントを準備するときに_docコメント_を使用します。

この章では、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ツールは、次のタグを認識します-

Tag	Description	Syntax
@author	Adds the author of a class.	@author name-text
\{@code}	Displays text in code font without interpreting the text as HTML markup or nested javadoc tags.	\{@code text}
\{@docRoot}	Represents the relative path to the generated document’s root directory from any generated page.	\{@docRoot}
@deprecated	Adds a comment indicating that this API should no longer be used.	@deprecated deprecatedtext
@exception	Adds a *Throws *subheading to the generated documentation, with the classname and description text.	@exception class-name description
\{@inheritDoc}	Inherits a comment from the* nearest* inheritable class or implementable interface.	Inherits a comment from the immediate surperclass.
\{@link}	Inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class.	\{@link package.class#member label}
\{@linkplain}	Identical to \{@link}, except the link’s label is displayed in plain text than code font.	\{@linkplain package.class#member label}
@param	Adds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section.	@param parameter-name description
@return	Adds a "Returns" section with the description text.	@return description
@see	Adds a "See Also" heading with a link or text entry that points to reference.	@see reference
@serial	Used in the doc comment for a default serializable field.	@serial field-description
include	exclude	@serialData
Documents the data written by the writeObject( ) or writeExternal( ) methods.	@serialData data-description	@serialField
Documents an ObjectStreamField component.	@serialField field-name field-type field-description	@since
Adds a "Since" heading with the specified since-text to the generated documentation.	@since release	@throws
The @throws and @exception tags are synonyms.	@throws class-name description	\{@value}
When \{@value} is used in the doc comment of a static field, it displays the value of that constant.	\{@value package.class#field}	@version

例

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

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

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/AddNuml...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating/package-framel...
Generating/package-summaryl...
Generating/package-treel...
Generating/constant-valuesl...
Building index for all the packages and classes...
Generating/overview-treel...
Generating/index-alll...
Generating/deprecated-listl...
Building index for all classes...
Generating/allclasses-framel...
Generating/allclasses-noframel...
Generating/indexl...
Generating/help-docl...
1 warning
$

ここで生成されたすべてのドキュメントをチェックできます-https://www.finddevguides.com/java/indexl[AddNum]。 JDK 1.7を使用している場合、javadocは素晴らしい stylesheet.css を生成しないため、https://docs.oracle.com/javase/7/docs/api/stylesheet.cssから標準スタイルシートをダウンロードして使用することをお勧めします。