使用 javadoc 生成开发文档

编写完自己的程序，如何生成其对应的开发者文档以方便我们日后查看呢？使用 javadoc 开发工具即可生成一个开发者文档。本文将介绍使用 javadoc 如何生成开发者文档以及注意的问题。

1.文档注释

注释分为：

• 单行注释：// 注释内容
• 多行注释：/* 注释内容 */
• 文档注释：/** 注释内容 */

文档注释属于多行注释。但值得注意的是，他们有一个明显的区别：

• 文档注释的内容可以生成一个开发者文档，而多行注释不可以。

也就是说，要想在开发文档中看到注释内容，那么必须使用文档注释，即使用 /** 注释内容*/ 形式进行注释。

2. 利用 Javadoc 生成开发文档

2.1 在 dos 命令下使用 javadoc 生成开发文档

在 dos 命令中输入 javadoc 可以查看 javadoc 的用法以及参数。在 dos 命令中使用 javadoc 生成开发文档的格式为：

• javadoc -d 存放文档的路径 java 源文件

例如对 demo.java 文件在cmd中生成开发文档，并将生成的开发文档存储在 E:\qq 路径下：

javadoc -d E:\qq  demo.java

使用 javadoc 工具要注意的细节：

1. 如果一个类需要使用 javadoc 工具生成一个软件开发者文档，那么该类必须使用public修饰。
2. 文档注释的内容一般都是位于类或方法的上面。

下面我们用一个小 Demo 来说明。该 Demo 中有两处文档注释。一是对 Demo 类的注释，类注释写在所注释类的上方，并且该类使用 public 修饰。在类注释中可以写作者信息和版本信息；二是对 main 方法的注释，写在所注释方法的上方。

/**
    该类是用于模拟QQ软件的
    @author Megan 
    @version qq 1.0
*/
public class Demo 
{
    /**
操作流程如下：
         1. 首先输入用户名和密码
         2. 校验用户名和密码
         3. 展示好友列表
    */
    public static void main(String[] args) 
    {
        System.out.println("请输入用户名与密码");
        System.out.println("校验用户名和密码");
        System.out.println("展示好友列表");
    }
}

在 dos 命令行中输入

• javadoc -d Myqq -author -version Demo.java

-d 表示生成的目录位置
Myqq表示生成文档所在当前目录下的文件夹名
-author是作者的名字
-version是版本信息

2.2 在 Myeclipse 中利用 javadoc 生产开发文档

首先打开代码，编写 javadoc 注释，javadoc 注释要尽量写的详细，这样别人在没有源码的情况下才知道如何使用您的代码。

import java.util.Arrays;

/**
 1. 这是一个测试类
 2. @author Megan
 */
public class Demo {

    /**
     * 姓名
     */
    public String name;

    /**
     * 年龄
     */
    public int Age;
    public String[] sarr;

    /**
     * 主函数
     * @param args
     */
public static void main(String[] args){
        String name="hello world";
        Print(name);

}
    /**
     * 打印函数
     * @param name
     */
private static void Print(String name){
        System.out.println(name);
    }
}

1. 点击 Myeclipse 的【Project】菜单，选择【Generate JavaDoc】选项。
   （1）选择您要生成JavaDoc的工程；
   （2）选择哪些级别的内容生成JavaDoc，默认为public，如果选择private则会全部内容都生成；
   （3）选择doc的生成位置，默认为工程目录下，建议不要修改；
   
   （4）点击【Next】按钮。

2. 勾选Document Title，然后填写文档标题，点击【Next】按钮。

   

3. 选择使用的jdk版本，点击【Finish】按钮

   

4. 项目下生成一个【doc】的目录，里面存放着javadoc文档，打开doc目录，找到index.html

   

5. 打开 index.html，可以看到一个完整的API文档、javadoc就生成了。