📜  Java-文档注释

📅  最后修改于: 2020-12-21 01:55:43             🧑  作者: Mango


Java语言支持三种类型的注释-

Sr.No. Comment & Description
1

/* text */

The compiler ignores everything from /* to */.

2

//text

The compiler ignores everything from // to the end of the line.

3

/** documentation */

This is a documentation comment and in general its called doc comment. The JDK javadoc tool uses doc comments when preparing automatically generated documentation.

本章都是关于解释Javadoc的。我们将看到如何利用Javadoc为Java代码生成有用的文档。

什么是Javadoc?

Javadoc是JDK附带的工具,用于从Java源代码生成HTML格式的Java代码文档,而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标记。例如,以下示例将

…. 用于标题,并将

用于创建段落中断-

/**
* 

Hello, World!

* The HelloWorld program implements an application that * simply displays "Hello World!" to the standard output. *

* 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 Adds a “Version” subheading with the specified version-text to the generated docs when the -version option is used. @version version-text

以下程序使用了一些可用于文档注释的重要标签。您可以根据需要使用其他标签。

有关AddNum类的文档将在HTML文件AddNum.html中生成,但同时还将创建一个名称为index.html的主文件。

import java.io.*;

/**
* 

Add Two Numbers!

* The AddNum program implements an application that * simply adds two given integer numbers and Prints * the output on the screen. *

* Note: 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下载并使用标准样式表。