Java - 文档评论

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

Sr.No. 评论&说明
1

/* text */

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

2

//text

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

3

/**documentation */

这是文档注释,通常称为 doc注释.准备自动生成的文档时, JDK javadoc 工具使用 doc comments .

本章是关于解释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工具识别以下标签&minus ;

标签 描述 语法
@ author 添加类的作者. @author name-text
{@ code} 以代码字体显示文本而不将文本解释为HTML标记或嵌套的javadoc标记. {@ code text}
{@ docRoot} 表示相对路径从任何生成的页面到生成的文档的根目录. {@ docRoot}
@ deprecated 添加评论表示不再使用此API. @deprecated deprecatedtext
@ exception 使用类名和说明文本向生成的文档添加投掷子标题. @ exception class-name description
{ @inheritDoc} 从最近的可继承类或可实现的接口继承注释. 从立即继承注释超级.
{@ link} 插入带有可见文本标签的内联链接,指向引用类的指定包,类或成员名称的文档. {@link package.class#member label}
{@ linkplain} 与{@link}相同,但链接的标签除外以纯文本显示而不是代码字体. {@ linkplain package.class#member label}
@ param 在"参数"部分添加一个带有指定参数名称的参数,后跟指定的描述. @param参数名称描述
@ return 添加带有描述文本的"返回"部分. @ return description
@ see 添加"另请参阅"使用指向引用的链接或文本条目标题. @参见参考
@ serial 用于默认可序列化字段的doc注释. @ serial field-description |包括|排除
@ serialData 记录由writeObject()或writeExternal()方法. @ serialData data-description
@ serialField 记录一个ObjectStreamField组件. @serialField field-name field-type field-description
@ since 使用指定的自动文本向生成的文档添加"Since"标题. @自发布以来
@ throws @throws and @exception标签是同义词. @throws class-name description
{@ value} 在静态字段的doc注释中使用{@value}时,它会显示该常量的值. {@ value package.class #field}
@version 使用-version选项时,将指定版本文本的"Version"子标题添加到生成的文档中. @ version version-text

示例

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

有关AddNum类的文档将在HTML文件AddNum.html中生成,但同时具有名称索引的主文件.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