zoukankan      html  css  js  c++  java
  • Java 文档注释

    Java只是三种注释方式。前两种分别是// 和/* */,第三种被称作说明注释,它以/** 开始,以 */结束。

    说明注释允许你在程序中嵌入关于程序的信息。你可以使用javadoc工具软件来生成信息,并输出到HTML文件中。

    说明注释,是你更加方面的记录你的程序的信息。


    javadoc 标签

    javadoc工具软件识别以下标签:

    标签描述示例
    @author 标识一个类的作者 @author description
    @deprecated 指名一个过期的类或成员 @deprecated description
    {@docRoot} 指明当前文档根目录的路径 Directory Path
    @exception 标志一个类抛出的异常 @exception exception-name explanation
    {@inheritDoc} 从直接父类继承的注释 Inherits a comment from the immediate surperclass.
    {@link} 插入一个到另一个主题的链接 {@link name text}
    {@linkplain} 插入一个到另一个主题的链接,但是该链接显示纯文本字体 Inserts an in-line link to another topic.
    @param 说明一个方法的参数 @param parameter-name explanation
    @return 说明返回值类型 @return explanation
    @see 指定一个到另一个主题的链接 @see anchor
    @serial 说明一个序列化属性 @serial description
    @serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据 @serialData description
    @serialField 说明一个ObjectStreamField组件 @serialField name type description
    @since 标记当引入一个特定的变化时 @since release
    @throws 和 @exception标签一样. The @throws tag has the same meaning as the @exception tag.
    {@value} 显示常量的值,该常量必须是static属性。 Displays the value of a constant, which must be a static field.
    @version 指定类的版本 @version info

    文档注释

    在开始的/**之后,第一行或几行是关于类、变量和方法的主要描述.

    之后,你可以包含一个或多个何种各样的@标签。每一个@标签必须在一个新行的开始或者在一行的开始紧跟星号(*).

    多个相同类型的标签应该放成一组。例如,如果你有三个@see标签,可以将它们一个接一个的放在一起。

    下面是一个类的说明注释的示例:

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

    javadoc输出什么

    javadoc工具将你Java程序的源代码作为输入,输出一些包含你程序注释的HTML文件。

    每一个类的信息将在独自的HTML文件里。javadoc也可以输出继承的树形结构和索引。

    由于javadoc的实现不同,工作也可能不同,你需要检查你的Java开发系统的版本等细节,选择合适的Javadoc版本。

    实例

    下面是一个使用说明注释的简单实例。注意每一个注释都在它描述的项目的前面。

    在经过javadoc处理之后,SquareNum类的注释将在SquareNum.html中找到。

    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
    $
  • 相关阅读:
    php 如何提升
    PHP判断客户端是否使用代理服务器及其匿名级别
    前端基础之BMO和DOM
    前端基础之JavaScript
    前端基础之CSS标签样式
    前端基础之CSS选择器
    前端基础之HTML标签
    面向对象之反射 元类
    面向对象之多态以及魔法函数
    面向对象之封装
  • 原文地址:https://www.cnblogs.com/toutou/p/java_javadoc.html
Copyright © 2011-2022 走看看