Package - Oracle JDK - 终端命令 - javadoc

文章摘要： 从 Java 源代码中的特殊格式的注释中自动生成 API 文档。

简介

javadoc 命令解析一组 Java 源文件中的声明和文档注释，并生成一组相应的 HTML 页面，这些页面描述（默认情况下）公共类和受保护类、嵌套类（但不是匿名内部类）、接口、构造函数、方法和字段。您可以使用 javadoc 命令为一组源文件生成 API 文档或实现文档。
Javadoc 注释是置于代码之上的特殊类型的注释，它们以 /** 开始，并以 */ 结束。
Javadoc 工具解析这些注释，并从中生成 HTML 格式的文档。

格式

提示

javadoc {<包>|<源文件>} [<选项>] [<标记>]

包

要记录的包的名称，用空格分隔。
例如 java.lang java.lang.reflect java.awt 。
默认情况下，javadoc 在当前目录和子目录中查找指定的包。使用 -sourcepath 选项指定在其中查找包的目录列表。

源文件

要记录的 Java 源文件的名称，用空格分隔，例如 Class.java Object.java Button.java 。
默认情况下，javadoc 在当前目录中查找指定的类。
但是，您可以指定类文件的完整路径并使用通配符，例如 /home/src/java/awt/Graphics*.java 。
您还可以指定相对于当前目录的路径。

选项

生成的文件结构

apidocs：顶级目录
    index.html：设置 HTML 框架的初始页面
    overview-summary.html：包含摘要的软件包列表
    overview-tree.html：所有包的类层次结构
    deprecated-list.html：所有软件包的 API 已弃用
    constant-values.html：所有包的静态字段值
    serialized-form.html：所有包的序列化表单
    overview-frame.html：所有包均显示在左上角的框架中
    allclasses-frame.html：所有类都显示在左下角框架中
    help-doc.html： 有关 Javadoc 页面组织的帮助
    index-all.html：创建的默认索引未使用 -splitindex 选项
    index-files：使用 -splitindex 选项创建的目录
        index-<number>.html：使用 -splitindex 选项创建的索引文件
    package-list：用于解析外部引用的包名称
    stylesheet.css：定义字体、颜色、位置等

java：包目录
    applet：子包目录
        Applet.html：小程序类页面
        AppletContext.html：AppletContext 接口
        AppletStub.html：AppletStub 接口
        AudioClip.html：AudioClip 接口
        package-summary.html：带摘要的类
        package-frame.html：打包类以显示在左下角框架中
        package-tree.html：此包的类层次结构
        package-use.html：此包的用途
        doc-files：图像和示例文件目录
        class-use：图像和示例文件位置
            - Applet.html：Applet 类的使用
            - AppletContext.html：AppletContext 接口的使用
            - AppletStub.html：AppletStub 接口的使用
            - AudioClip.html：AudioClip 接口的使用

src-html： 源代码目录
    java：包目录
        applet：子包目录
            - Applet.html：小程序源代码
            - AppletContext.html：AppletContext 源代码
            - AppletStub.html：AppletStub 源代码
            - AudioClip.html：AudioClip 源代码

标记

@author：指定类的作者。
@deprecated：标记类、方法或字段已过时，不推荐使用。
@exception：与 @throws 相同，用于描述方法可能抛出的异常。
@param：描述方法的参数。
@return：描述方法的返回值。
@see：提供到其他类或方法的链接。
@since：指定何时添加了类、方法或字段。
@serial：用于说明序列化相关的信息。
@serialField：用于说明一个对象的序列化字段。
@serialData：用于描述序列化数据。
@throws：描述方法可能抛出的异常。
@version：指定类的版本信息。

案例

注释类型

类注释：位于每个类的开头，描述类的功能和用法。
接口注释：位于每个接口的开头，描述接口的功能和用法。
方法注释：位于每个方法的上方，描述方法的功能、参数、返回值和可能抛出的异常。
字段注释：位于每个字段的上方，描述字段的含义和用途。
构造器注释：位于每个构造器的上方，描述构造器的功能和用法。