【Java基础笔记】1-7 JavaDoc文档

§1-7 JavaDoc 文档

JavaDoc 用于生成自己的 API 文档，关于 Oracle 官方的 JDK 文档，见此。

文档注释信息可以加在类上，也可以加在方法上。请见下文。

目录

• §1-7 JavaDoc 文档
  • 1-7.1 参数信息
  • 1-7.2 加入文档注释
  • 1-7.3 生成 JavaDoc 文档

1-7.1 参数信息

JavaDoc 内可添加的参数有：

/**
	*@author 作者名
	*@deprecated 指定一个过期的类或成员
	*@exception 标志一个类抛出的异常
	*@version 版本号
	*@since 指明需要最早使用的 JDK 版本（最低）
	*@param 参数名
	*@return 返回值情况
	*@see 指定到另一个主题的链接
	*@throws 异常抛出情况
*/

1-7.2 加入文档注释

新建一个 Java 类，并键入如下内容：

//加在类上：类的注释

/**
 * @author zebt
 * @version 1.0
 * @since 1.8
 */
public class Doc {
    String name;    //添加实例变量

    //加在方法上：方法的注释

    /**
     * @author zebt
     * @param name
     * @return
     * @throws Exception
     */
    public String test(String name) throws Exception{
        return name;
    }

}

如图所示：

1-7.3 生成 JavaDoc 文档

1. 用命令行生成

   • 打开.java文件所在目录；

   • 在该目录下打开命令提示符；

   • 键入命令：javadoc -encoding UTF-8 -charset UTF-8 <目标文件.java>，回车；

     javadoc 命令的部分参数如下：

     • 自 Java 9 后，可添加参数 -html5 生成 HMTL 5 输出；
     • -d <directory> 可指定目录生成；
     • -author 包含 @author 段；

   • 可以看到文件夹下多出了如图所示文件：

     

   • 打开index.html，即帮助文档首页，如图：

     

2. 在 IDEA 中生成

   • 在菜单栏中选择Tools --> Generate JavaDoc

     

   • 在弹出的对话框中指定输出目录、其他命令行参数后点击OK即可。

     

     若出现报错：javadoc: 错误 - 无法读取Input length = 1，请查看文件路径是否含有中文字符。

   • 或在 IDEA 下的Terminal使用命令行生成。