Java基础语法:JavaDoc
阅读原文时间:2023年07月09日阅读:1

一、简介

  • JavaDoc是一种将注释生成HTML文档的技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
  • 也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。

二、注释标签

常用标签列表:

  1. 作者:@author
  2. 版本号:@version
  3. 需要使用的JDK最早版本:@since
  4. 参数:@param
  5. 返回值:@return
  6. 抛出的异常:@throws

注意:

  • 注释标签必须在JavaDoc注释中使用。
  • JavaDoc注释可以用在类、变量和方法上。
  • JavaDoc注释在开始的'/**'之后,第一行或几行是关于类、变量和方法的主要描述
  • 之后,你可以包含一个或多个各种各样的注释标签。每一个注释标签必须在一个新行的开始,或者在一行的开始紧跟星号后面。
  • 多个相同类型的标签应该放成一组。例如,如果你有三个'@param'标签,可以将它们一行接一行的放在一起。

示例:

/**
 * 这是一个方法
 *
 * @author conyoo
 * @version 1.0
 * @since 1.8
 * @param parameter 一个参数
 * @return 一个返回值
 * @throws Exception 一个异常
 */
public String test(String parameter) throws Exception {
    return parameter;
}

三、javadoc命令

  • 开发者可以在命令行中使用'javadoc'命令,来生成JavaDoc文档。
  • 'javadoc'命令既可以处理包,也可以处理java源文件。

语法:javadoc [options] [packagenames] [sourcefiles] [@files]

注意:

  • 设置编码参数'-encoding'和字符集参数'-charset'为'UTF-8',可以解决中文乱码问题。
  • 'javadoc'命令不递归作用于子包,所以处理包时不允许对包名使用通配符,必须列出希望建立文档的每一个包。
  • '[@files]':为了简化javadoc命令,你可以把需要建立文档的文件名和包名放在一个或多个文本文件中。

示例:

D:\workspace\demo\src\com\cnblogs\www\example>javadoc -encoding UTF-8 -charset UTF-8 HelloWorld.java