转载

Java文档注释

 上一篇

Java支持三种类型的注释。前两个是//和/**/。第三类被称为文档注释。它是从字符序列/*,并用*/结束。

文档注释允许嵌入程序的信息到程序本身。然后,可以使用javadoc工具来提取信息,并把它放到一个HTML文件。

文档注释使它方便地记录程序。

javadoc标签:

javadoc工具识别以下标记:

标签 描述 实例
@author Identifies the author of a class. @author description
@deprecated Specifies that a class or member is deprecated. @deprecated description
{@docRoot} Specifies the path to the root directory of the current documentation Directory Path
@exception Identifies an exception thrown by a method. @exception exception-name explanation
{@inheritDoc} Inherits a comment from the immediate superclass. Inherits a comment from the immediate surperclass.
{@link} Inserts an in-line link to another topic. {@link name text}
{@linkplain} Inserts an in-line link to another topic, but the link is displayed in a plain-text font. Inserts an in-line link to another topic.
@param Documents a method's parameter. @param parameter-name explanation
@return Documents a method's return value. @return explanation
@see Specifies a link to another topic. @see anchor
@serial Documents a default serializable field. @serial description
@serialData Documents the data written by the writeObject( ) or writeExternal( ) methods @serialData description
@serialField Documents an ObjectStreamField component. @serialField name type description
@since States the release when a specific change was introduced. @since release
@throws Same as @exception. The @throws tag has the same meaning as the @exception tag.
{@value} Displays the value of a constant, which must be a static field. Displays the value of a constant, which must be a static field.
@version Specifies the version of a class. @version info

文档注释:

之后开始/ **,第一行或行变得类,变量或方法的主要描述。

在此之后,可以包括一个不同的@标记以上。每一个@标记必须在开始一个新行的开头或跟随一个星号(*),即在一行的开头。

同一类型的多个标签应该被组合在一起。例如,如果有三个@标记,把它们一个接一个。

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

 /** * This class draws a bar chart. * @author Zara Ali * @version 1.2 */

什么javadoc输出?

javadoc程序需要输入Java程序的源文件,输出包含该程序的文档多个HTML文件。

有关每个类信息将在其自己的HTML文件。 Java实用程序的javadoc也将输出一个索引和一个层次树。其他HTML文件可以生成。

由于javadoc中的不同实现可能有不同的工作,需要检查同伴的Java开发系统特定于版本的详细信息的说明。

例子:

下面是一个使用文档注释的示例程序。请注意每个注释前面紧邻,它描述了项目的方式。

由javadoc的处理后,对SquareNum类的文档将在SquareNum.htmll。

 import java.io.*;  /** * This class demonstrates documentation comments. * @author Ayan Amhed  * @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 {       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);    } }

现在,上述过程用javadoc工具作为SquareNum.java文件如下:

 $ javadoc SquareNum.java Loading source file SquareNum.java... Constructing Javadoc information... Standard Doclet version 1.5.0_13 Building tree for all the packages and classes... Generating SquareNum.html... SquareNum.java:39: 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... Generating stylesheet.css... 1 warning $

可以检查所有生成的文档在这里: SquareNum.

 上一篇
正文到此结束
Loading...