文档（Documentation）

优质

小牛编辑

126浏览

2023-12-01

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

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

Sr.No.

评论和描述

/* text */

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

//text

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

/** documentation */

这是一个文档注释，通常称为doc comment 。 JDK javadoc工具在准备自动生成的文档时使用doc comments 。

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

什么是Javadoc？

Javadoc是一个JDK附带的工具，它用于从Java源代码生成HTML格式的Java代码文档，这需要以预定义格式的文档。

以下是一个简单的示例，其中/*....*/中的行是Java多行注释。同样，//之前的行是Java单行注释。

例子 (Example)

/**
* 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>作为标题，

用于创建段落 -

例子 (Example)

/**
* <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	添加类的作者。	@author name-text
{@code}	以代码字体显示文本而不将文本解释为HTML标记或嵌套的javadoc标记。	{@code text}
{@docRoot}	表示从任何生成的页面生成的文档的根目录的相对路径。	{@docRoot}
@deprecated	添加注释，指示不再使用此API。	@deprecated deprecatedtext
@exception	使用类名和描述文本向生成的文档添加“ Throws子标题。	@exception类名描述
{@inheritDoc}	从nearest可继承类或可实现的接口继承注释。	继承来自直接超类的注释。
{@link}	插入带有可见文本标签的内嵌链接，该链接指向引用类的指定包，类或成员名称的文档。	{@link package.class＃member label}
{@linkplain}	与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。	{@linkplain package.class＃member label}
@param	将具有指定参数名称的参数后跟指定描述添加到“参数”部分。	@param参数名称描述
@return	添加带有描述文本的“返回”部分。	@return描述
@see	添加“另请参见”标题，其中包含指向引用的链接或文本条目。	@see参考
@serial	用于默认可序列化字段的doc注释中。	@serial字段描述\| 包括\| 排除
@serialData	记录writeObject（）或writeExternal（）方法写入的数据。	@serialData数据描述
@serialField	Documents an ObjectStreamField component.	@serialField field-name字段类型字段描述
@since	使用指定的自动文本向生成的文档添加“Since”标题。	@since发布
@throws	@throws和@exception标签是同义词。	@throws类名描述
{@value}	在静态字段的doc注释中使用{@value}时，它会显示该常量的值。	{@value package.class #field}
@version	使用-version选项时，将指定版本文本的“版本”子标题添加到生成的文档中。	@version版本文本

例子 (Example)

以下程序使用了几个可用于文档注释的重要标记。您可以根据自己的要求使用其他标签。

有关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下载并使用标准样式表