Java 文档注释 Intellij IDEA Generate JavaDoc

2022 年 10 月 11 日
江西
本文字数：1018 字
阅读完需：约 3 分钟

一、说明

文档注释(Java Doc Comments)是指允许你在程序中嵌入关于程序的信息，使你更加方便的记录你的程序的信息
你可以使用 Javadoc 工具软件来生成信息，并输出到 HTML 文件中
Generate JavaDoc 是 Sun 公司提供的一种工具，它可以从程序源代码中抽取类、方法、成员等注释，形成一个和源代码配套的 API 帮助文档

二、理解

Java 支持三种注释方式

// 这是一般注释
/** 这是一般注释*/
/** * 这是文档注释*/

复制代码

一个文档注释由描述部分和标记部分两部分组成
文档注释第一行以特殊的文档定界符 /** 开头，描述部分和标记部分必须分开，且描述段落必须在标记段落之前，每一行注释都应该保持同样距离的缩进

/** * 描述部分(description) 用来描述类和方法的功能特点等 *  * 标记部分(block tags) 用于描述标签*/

复制代码

public interface Executor {
    /**     * Executes the given command at some time in the future.  The command     * may execute in a new thread, in a pooled thread, or in the calling     * thread, at the discretion of the {@code Executor} implementation.     *     * @param command the runnable task     * @throws RejectedExecutionException if this task cannot be     * accepted for execution     * @throws NullPointerException if command is null     */    void execute(Runnable command);}

复制代码

Javadoc 标签

类文档标记中的标记部分中要按照 @param、@return、@throws、@since、@see、@deprecated 的顺序进行排列，@return 后说明返回值类型，而没有返回变量名

三、实现

通过 Intellij IDEA 自带的 Generate JavaDoc 功能，可以自动生成文档注释

Generate JavaDoc scope 生成文档范围
Whole project 整个项目
File '....src\com\..... 当前文件
Custom scope 自定义范围
lnclude JDK and library sources in -sourcepath 包含 JDK 和第三方库
link to JDK documentation 链接到 JDK 文档，即 API
output directy 生成文档存放的位置
private、package、protected、public 生成文档的级别，即类和方法
@use 等是指生成文档包含的内容信息
Generate hierarchy tree 包含层级树
Generate navigation bar 包含导航
Generate index 包含索引
Separate index per letter 每个字母的单独索引
Locale 语言类型，一般设置为zh-CN
Other command line arguments 其它命令参数，一般用于设置统一文件编码与字符集 -encoding UTF-8 -charset UTF-8
Maximum heap size(Mb) 最大堆大小