3.9 使用Java的文档注释

 

Java支持三种形式的注释。前两种是// 和/* */。第三种方式被称为文档注释。它以“/**”开始，以“*”标志结束。文档注释提供将程序信息嵌入程序的功能。开发者可以使用javadoc工具将信息取出，然后转换为HTML文件。文档注释提供了编写程序文档的便利方式。javadoc工具生成的文档几乎人人都看过，因为Sun的Java API文档库就是这么生成的。

javadoc标记

javadoc实用程序识别下列标记：

Tag标记	意义
@author	确定类的作者
@deprecated	指示反对使用这个类或成员
{@docRoot}	指定当前文档的根目录路径 (Java 2的1.3版新增)
@exception	确定一个方法引发的异常
{@link}	插入对另一个主题的内部链接
@param	为方法的参数提供文档
@return	为方法的返回值提供文档
@see	指定对另一个主题的链接
@serial	为默认的可序列化字段提供文档
@serialData	为writeObject( )或者writeExternal( )方法编写的数据提供文档
@serialField	为ObjectStreamField组件提供文档
@since	当引入一个特定改变时，声明发布版本
@throws	与@exception相同
@version	指定类的版本

 

 

 

 

 

 

 

 

 

 

 

 正如上面看到的那样，所有的文档标记都以“(@)”标志开始。在一个文档注释中，也可以使用其他的标准HTML标记。然而，一些标记（如标题）是不能使用的，因为它们会破坏由javadoc生成的HTML文件外观。

可以使用文档注释为类、接口、域、构造函数和方法提供文档。在所有这些情况中，文档注释必须紧接在被注释的项目之前。为变量做注释，可以使用@see, @since, @serial, @serialField, 和@deprecated文档标记。为类做注释，可以使用@see, @author, @since, @deprecated, 和@version文档标记。方法可以用@see, @return, @param, @since, @deprecated, @throws, @serialData, 和@exception做标记。而{@link} 或 {@docRoot}标记可以用在任何地方。下面详细列出了每个标记的使用方法：

@ author

标记@author 指定一个类的作者，它的语法如下：

@author description

其中， description 通常是编写这个类的作者名字。标记@author 只能用在类的文档中。在执行javadoc时，你需要指定-author 选项，才可将@author 域包括在HTML文档中。

@deprecated

@deprecated 标记指示不赞成使用一个类或是一个成员。建议使用@see 标记指示程序员其他可用的选择。其语法如下：

@deprecated description

其中description 是描述反对的信息。由@deprecated 标记指定的信息由编译器识别，包括在生成的.class文件中，因此在编译Java源文件时，程序员可以得到这个信息。@deprecated 标记可以用于变量，方法和类的文档中。

{@docRoot}

{@docRoot}指定当前文档的根目录路径。

@exception

@exception 标记描述一个方法的异常，其语法如下：

@exception exception-name explanation

其中，异常的完整名称由exception-name指定，explanation 是描述异常如何产生的字符串。@exception 只用于方法的文档。

{@link}

{@link} 标记提供一个附加信息的联机超链接。其语法如下：

{@link name text}

其中，name 是加入超链接的类或方法的名字， text 是显示的字符串。

@param

@param 标记注释一个方法的参数。其语法如下所示：

@param parameter-name explanation

其中parameter-name指定方法的参数名。这个参数的含义由explanation描述。@param 标记只用在方法的文档中。

@return

@return 标记描述一个方法的返回值。其语法如下：

@@return explanation

其中，explanation 描述方法返回值的类型和含意。@return 标记只用在方法的文档中。

@see

@see 标记提供附加信息的引用。最常见的使用形式如下所示：

@see anchor

@see pkg.class#member text

在第一种格式中，ancho 是一个指向绝对或相对URL的超链接。第二种格式， pkg.class#member 指示项目的名字，text是项目的文本显示。文本参数是可选的，如果不用，显示由pkg.class#membe 指定的项目。成员名，也是可选的。因此，除了指向特定方法或者字段的引用之外，你还可以指定一个引用指向一个包，一个类或是一个接口。名字可以是完全限定的，也可以是部分限定的。但是，成员名（如果存在的话）之前的点必须被替换成一个散列字符。

@serial

@serial 标记为默认的可序列化字段定义注释文档。其语法如下：

@serial description

其中， description 是字段的注释。

@serialData

@serialData 标记为writeObject( )或者 writeExternal( )方法编写的数据提供文档。其语法如下：

@serialData description

其中，description 是数据的注释。

@serialField

@serialField 标记为ObjectStreamField组件提供注释，其语法如下：

@serialField name type description

其中，name是域名，type是域的类型，description是域的注释。

@since

@since标记声明由一个特定发布版本引入的类或成员。其语法如下：

@since release

其中，release是指示这个特性可用的版本或发布的字符串。@since 标记可以用在变量、方法和类的文档中。

@throws

@throws 标记与@exception标记的含义相同。

@version

@version标记指示类的版本。其语法如下：

@version info

其中，info 是包含版本信息的字符串，典型情况下是如2.2这样的版本号。@version标记只用在类的文档中。在执行javadoc时，指定-version 选项，可将@version域包含在HTML文档中。

文档注释的一般形式

在用/**开头后，第一行，或者头几行是类、变量或方法的主要描述。其后，可以包括一个或多个不同的@标记。每个@标记必须在一个新行的开头，或者跟随一个星号(*)。同类型的多个标记应该组合在一起。例如，如果有三个@see标记，最好是一个挨着一个。

下面是一个类的文档注释的例子：

/**
 * This class draws a bar chart.
 * @author Herbert Schildt
 * @version 3.2
*/

javadoc的输出

javadoc程序将Java程序的源文件作为输入，输出几个包含该程序文档的HTML文件。每个类的信息在其自己的HTML文件中。同时，javadoc还输出一个索引和一个层次结构树。Javadoc还可生成其他HTML文件。不同实现版本的javadoc可能工作方式有所不同，应该仔细阅读Java开发系统的说明书以了解此版本的细节处理。

一个使用文档注释的例子

下面是一个使用文档注释的程序范例。注意每个注释都在它描述的对象之前。在javadoc处理之后，SquareNum.html就是关于SquareNum类的文档。

import java.io.*;

/**
 * This class demonstrates documentation comments.
 * @author Herbert Schildt
 * @version 1.2
*/
public class SquareNum {
  /**
   * This method returns the square of num.
   * This is a multiline description.  You can use
   * as many lines as you like.
   * @param num The value to be squared.
   * @return num squared.
  */
  public double square(double num) {
    return num * num;
  }

  /**
   * This method inputs a number from the user.
   * @return The value input as a double.
   * @exception IOException On input error.
   * @see IOException
  */
  public double getNumber() throws IOException {
    // create a BufferedReader using System.in
    InputStreamReader isr = new InputStreamReader(System.in);
    BufferedReader inData = new BufferedReader(isr);
    String str;

    str = inData.readLine();
    return (new Double(str)).doubleValue();
  }
  /**
   * This method demonstrates square().
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
  */

  public static void main(String args[])
    throws IOException
  {
    SquareNum ob = new SquareNum();
    double val;

    System.out.println("Enter value to be squared: ");
    val = ob.getNumber();
    val = ob.square(val);

    System.out.println("Squared value is " + val);
  }