使用javadoc工具生成API文档

由于文档注释适用于生成API文档的，而API文档主要用于说明类、方法、成员变量的功能。因此javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他部分的注释。而且javadoc工具默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释，如果开发者希望javadoc工具可以提取private修饰的内容，则可以在使用javadoc工具时增加-private选项

文档注释以斜线后紧跟两个星号（/**）开始，以星号后紧跟一个斜线（*/）结束，中间部分全部都是文档注释，会被提取到API文档中。

javadoc命令的基本用法

Javadoc  选项  Java源文件|包

javadoc命令对源文件、包生成API文档，在上面的语法格式中，Java源文件可以支持通配符，使用*.java来代表当前路径下所有的java源文件。

常用选项:

   -d<directory>:该选项指定一个路径，用于将生成的API文档存放到指定目录下

   -windowtitle<text>:该选项指定一个字符串，用于设置API文档的浏览器窗口标题

   -doctitle<html-code>:该选项制定一个HTML格式的文本，用于指定概述页面的标题

          只有对处于多个包下的源文件来生成API文档时，才有概述页面

     -header<html-code>>:该选项制定一个HTML格式的文本，包含每个页面的页眉

可通过Javadoc -help来查看javadoc命令的所有选项

注：只有对处于多个包下的源文件来生成API文档时，才有概述页面

乱码的情况下需要加

   设置源码编码方式：-encoding UTF-8

   指定输出的字符编码：-charset UTF-8

例如

package liu;
/**
 *Descriptio
 *<br>网站:<a href="http://www.baidu.com">百度连接</a>
 *<br>Copyright(C),2017-2017,Liu
 *<br>This program is protected by copyright laws.
 *<br>Program Name:
 *<br>Date:
 *@author Liu.zihui liuzh0929@gmail.com
 *@version 1.0
 *
*/
public class JavadocTest
{
   /**
    *简单测试成员变量
    */
    protected String name;
   /**
    *Test类的测试构造器
    */
   public static void main(String[] args)
   {
      System.out.println("Hello Word!");
   }
}

package xiaohui;
/**
 *Descriptio
 *<br>网站:<a href="http://www.baidu.com">百度连接</a>
 *<br>Copyright(C),2017-2017,Liu
 *<br>This program is protected by copyright laws.
 *<br>Program Name:
 *<br>Date:
 *@author Liu.zihui liuzh0929@gmail.com
 *@version 1.0
 *
*/
public class Test
{
   /**
    *简单测试成员变量
    */
   public int age;
   /**
    *Test类的测试构造器
    */
   public Test()
   {
      
   }
}

在命令行窗口执行命令生成API文档

javadoc -d apiodc -windowtitle test -doctitle study javadoc tool API -header myclass *Test.java

希望javadoc工具生成更详细的文档信息，可利用javadoc标记

@author:  作者
@version:  版本
@docroot:  表示产生文档的根路径
@deprecated:
不推荐使用的方法
@param:  方法的参数类型
@return:  方法的返回类型
@see:  用于指定参考的内容
@exception:
抛出的异常
@throws:  抛出的异常，和exception同义。

需要注意这些标记的使用是有位置限制的。
可以出现在类或者接口文档注释中的标记有：
   @see、@deprecated、@author、@version等。
可以出现在方法或者构造器文档注释中的标记有：
   @see、@deprecated、@param、@return、@throws、@exception等。
可以出现在文档注释中的有：
   @see、@deprecated等。 

package xiaohui;
/**
 *Descriptio
 *<br>网站:<a href="http://www.baidu.com">百度连接</a>
 *<br>Copyright(C),2017-2017,Liu
 *<br>This program is protected by copyright laws.
 *<br>Program Name:
 *<br>Date:
 *@author Liu.zihui liuzh0929@gmail.com
 *@version 1.0
 *
*/
public class JavadocTageTest
{
   /**
   *一个得到问候语字符串的方法
   *@param name 该参数指定向谁问候
   *@return 返回打招呼的字符串
   */
   public String hello(String name)
      {
         return name+",你好";
      }
}

在命令行窗口执行命令生成API文档

javadoc -d apiodc -windowtitle test -doctitle study javadoc tool API -header myclass -author -version *Test.java

注：javadoc工具默认不会提取@author和@version两个标记的信息，如果要提取这两个信息，需要在使用javadoc工具指定-author和-version两个选项

API文档中的包注释并不是直接放在java源文件中，而是必须另外指定，通常通过一个标准的HTML文件来提供包注释，这个文件被称为包描述文件，包描述文件的文件名通常是package.html，并于该包下所有的Java源文件放在一起，javadoc工具会自动寻找对应的包描述文件一并提取该报描述文件中的<body/>元素里的内容，作为该包的描述信息

doc针对包生成API

javadoc -d apiodc -windowtitle test -doctitle study javadoc tool API -header myclass -author -version liu xiaohui