Java文档注释 Intellij IDEA Generate JavaDoc

一、说明

• 文档注释(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 标签

标签	描述	说明与示例
@author	标识类的作者	只能用在类的标记文档中@author description
@version	标志类的版本	只能用在类的标记文档中@version info
@param	标志方法的参数	只能用在方法标记文档中@param parameter-name explanation
@return	标志返回值类型	只能用在方法标记文档中@return explanation
@exception	标志一个类抛出的异常	@exception exception-name explanation
@throws	标志方法或类抛出的异常	@throws NullPointerException if command is null
@see	引用其他类中的文档	@see anchor
@since	标志这个方法或类在哪个版本时添加的	@since release
@deprecated	标志一个过期的类或成员	在代码中使用被@deprecated标记的方法会收到编译器的警告@deprecated description

• 类文档标记中的标记部分中要按照@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) 最大堆大小