javadoc生成注释文档

一、javadoc

      javadoc是用于提取注释的工具，它是jdk安装的一部分。它采用java编译器的某些技术，查找程序内的特殊注释标签。它不仅解析由这些标签标记的信息，也将毗邻注释的类名或方法名抽取出来。javadoc生成的是一个html文件。

二、语法

          所有javadoc命令都只能在"/**"注释中出现，以"*/"结束。使用javadoc的方式主要有两种：嵌入html或是“文档标签”。独立文档标签是一些以"@"字符开头的命令，且要置于注释前的最前面，而行内文档标签则可以出现在javadoc注释的任何地方，也是以“@”开头，但要扩在花括号内。

          共有三种类型的注释文档，分别对应于注释文职后面的三种元素：类、域、方法。类注释正好位于类定义之前，域注释正好位于域定义之前，而方法注释位于方法定义之前。例：

/** A class comment */
public class Demo
{
    /** A field comment */
    public int i;
    /** A method commend */
    public void f(){}
} 

注意：javadoc只能为public和protected成员进行文档注释。（不过可以用-private进行标记，以便把private成员的注释包括在内）这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，这正是客户端程序员所期望的。

三、嵌入式html

        javadoc通过生成的html文档传送html指令。例：

/**
* you can <em>even</em> insert a list;
*<ol>
*<li> Item one
*<li> Item two
*<li> Item three
*</ol>
*/

四、 一些文档标签

1、@see     （引用其他类）

@see标签允许用户引用其他类的文档。

格式：  

@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name

2、@docRoot

该标签产生到文档根目录的相对路径，用于文档树页面显示超链接。

3、@inheritDoc

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

4、@version

格式：@version version-information

5、@author

格式：@author author-information

6、@param

格式：@param parameter-name description   其中parameter-name是方法的参数列表中的标示符。

7、@return

格式：@return discription     其中discription用来描述返回值的含义，可以延续数行。

8、@throws

格式：@throws fully-qualified-class-name description

9、@deprecated     该标签用于指出一些旧特性已由改进的新特性所取代。

五、效果展示(eclipse)

package com.zhou;
/**
 * @author zhouzixin
 * @version 1.0
 */
/** Model of a single arboreal unit. */ 
class Tree { 
  /** Current vertical aspect to the tip. */ 
  int height;  // 0 by default 
  /** Plant a seedling. Assume height can 
      be considered as zero. */ 
  Tree() { 
    System.out.println("Planting a seedling"); 
  } 
  /** Transplant an existing tree with a given height. */ 
  Tree(int i) { 
    System.out.println("Creating new Tree that is " 
      + i + " feet tall"); 
    height = i; 
  } 
  /** Produce information about this unit. */ 
  void info() { 
    System.out.println("Tree is " + height + " feet tall"); 
  } 
  /** Produce information with optional message. */ 
  void info(String s) { 
    System.out.println(s + ": Tree is " 
      + height + " feet tall"); 
  } 
} 
 
/** Simple test code for Tree class */ 
public class Demo16 { 
  /** Creates <b>Tree</b> objects and exercises the two 
      different <code>info()</code> methods. */ 
  public static void main(String[] args) { 
    for(int i = 0; i < 5; i++) { 
      Tree t = new Tree(i); 
      t.info(); 
      t.info("overloaded method"); 
    } 
    // Overloaded constructor: 
    new Tree(); 
  } 
}