java注释文档的生成

javadoc 注释

• javadoc注释以”/**“开始以”*/”结束。里面可以包含普通文本，HTML标记和javadoc标记，javadoc只处理源文件中在类/接口定义，方法，域，构造器之前的注释，而忽略为与其他地方的注释。举例如下：

/**
*第一个程序--<b>helloWorld</b>
*@author sam
*@version 1.0 
*/
public class myHelloWorld{
/**
*在main（）方法中使用的用于显示字符串的方法
*@see #main（java.lang.String[]）
*/
static String SDisp
}

• 上面例子中以@开头的标记就是javadoc标记，正确使用javadoc注释，非常有利于javadoc自动从源代码文件生成完整的格式化API文档，下面对这些标记详细说明。

  1. @author name-text指定作者，多个作者之间用逗号“，”隔离开。
  2. {@docroot} 代表产生文档的 根路径，举例如下：

/**
*see the <a href={@docroot}/copyright.html>copyright</a>
*/

3.@deprecated text 添加注释，表明不推荐使用该API。
4. @exception class-name desprition @throw的同意标记。
5. {@link package.class#member label}插入指向package.class#member的内嵌链接。例如假定注释文档中有如下文档： /** Use the {@link #getComponentAt(int,int) getComponentAt} method*/
6. 那么javadoc最终生成的HTML页面中将有如下内容：Use the <a href="Component.html#getComponentAt(int,int)"> getCompponentAt</a>method
7. @param parameter-name description 描述参数。
8. @return description 描述返回值
9. @see reference 添加引用标题，其中有指向reference 的链接或者文本项，

源代码示例

package weiyong.demo.javadoc;

/**
 * 类的说明
 * 
 * JavadocDemo类演示如何生成类的API文档<br>
 *@version:1.0 weiyong 2017.1.12<br> 
 *@author:96216
 *1.1water 2017.9.12增加了说明
 */
public class JavadocDemo {
    /*对于类的共有属性，也要写上相关的注释*/
    /**用于显示一个提示信息*/
    public final String message="This is  a demo for java doc.";
    /**
     * 这个方法是程序的入口，虚拟机载入这是雷达时候
     * 将从这个方法开始执行程序
     * @param args 命令行参数<br>
     */
    public static void main(String[] args) {
        JavadocDemo demo=new JavadocDemo();
        System.out.println(demo.message);
        System.out.println(demo.upcaseMessage());
        System.out.println(demo.getChars(2,6));

    }


    /**
     * 将message转换成一个大写的字符串
     * 
     * @return 转换成大写字符串后的message
     */
    private String upcaseMessage() {
        return message.toUpperCase();
    }

    /**
     * 从message中获取指定的子串
     * @param beginIndex 子串的开始下标
     * @param endIndex 子串结束的下标
     * @return 从beginIdex到endIndex之间的子串
     */
    private String getChars(int beginIndex, int endIndex) {
        return message.substring(beginIndex, endIndex);
    }
}

测试和运行

命令行方式

1. 因为JavadocDemo类属于weiyong.demo.javadoc包，所以先把JavadocDemo.java保存在工作目录下weiyong\demo\javadoc下。
2. 接着用javadoc weiyong.demo.javadoc
   JavadocDemo.java命令生成注释文档，如图所示。如果出现乱码，则加入-encoding utf-8代码。

• 再看目录中的内容，就会发现多了几个文档。表明注释文档生成成功。

• 用浏览器大爱JavadocDemo.html文件效果如图。

另一种方式：使用Eclipse生成注释文档

• 右键项目，点击Export–java–javadoc–javadoc Command–目录选择jdk\bin\javadoc.exe。点击finish即生成成功。