Java - 文档注释

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

先生。	评论和描述
1	*/ 文本 /* 编译器会忽略从 /* 到 */ 的所有内容。
2	//文本编译器会忽略从 // 到行尾的所有内容。
3	/ 文档 /* 这是一个文档注释，通常称为doc comment。JDK javadoc工具在准备自动生成的文档时使用文档注释。

先生。

评论和描述

/* 文本 */

编译器会忽略从 /* 到 */ 的所有内容。

//文本

编译器会忽略从 // 到行尾的所有内容。

/** 文档 */

这是一个文档注释，通常称为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!");
   }
}

输出

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!");
   }
}

输出

Hello World!

javadoc 标签

javadoc 工具可识别以下标签 -

标签	描述	句法
@作者	添加类的作者。	@作者姓名-文本
{@代码}	以代码字体显示文本，而不将文本解释为 HTML 标记或嵌套的 javadoc 标记。	{@代码文本}
{@docRoot}	表示从任何生成的页面到生成文档的根目录的相对路径。	{@docRoot}
@已弃用	添加一条注释，指示不应再使用此 API。	@deprecated 已弃用的文本
@例外	将Throws副标题添加到生成的文档中，其中包含类名和描述文本。	@Exception 类名描述
{@inheritDoc}	从最近的可继承类或可实现接口继承注释。	继承直接超类的注释。
{@关联}	插入带有可见文本标签的内联链接，该标签指向指定包、类或引用类的成员名称的文档。	{@link package.class#成员标签}
{@linkplain}	与 {@link} 相同，只是链接的标签以纯文本而不是代码字体显示。	{@linkplain package.class#member label}
@参数	将具有指定参数名称和后跟指定描述的参数添加到“参数”部分。	@param 参数名称描述
@返回	添加带有描述文本的“返回”部分。	@返回说明
@看	添加“另请参阅”标题，其中包含指向引用的链接或文本条目。	@参见参考资料
@串行	在文档注释中用于默认可序列化字段。	@串行字段描述 \| 包括 \| 排除
@串行数据	记录由 writeObject( ) 或 writeExternal( ) 方法写入的数据。	@serialData 数据描述
@serialField	记录 ObjectStreamField 组件。	@serialField 字段名称字段类型字段描述
@自从	将带有指定的since-text 的“Since”标题添加到生成的文档中。	@自发布以来
@抛出	@throws 和@exception 标签是同义词。	@throws 类名描述
{@价值}	当在静态字段的文档注释中使用 {@value} 时，它会显示该常量的值。	{@value 包.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);
   }
}

让我们编译并运行上面的程序，这将产生以下结果 -

Sum of 10 and 20 is :30

现在，使用 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