| 【精选】在 IDEA 上优雅地使用 Javadoc | 您所在的位置：网站首页 › idea标签快速注释 › 【精选】在 IDEA 上优雅地使用 Javadoc |
【精选】在 IDEA 上优雅地使用 Javadoc
|
文章目录
什么是 Javadoc ？为什么使用 Javadoc ？Javadoc 的使用规范是什么样的 ？何时需要 Javadoc ？Javadoc 结构
Javadoc 文档标签？类上的文档标签@see 参考{@link target} 链接@param 参数{@code text} 代码
@author 作者@since 启用时间@version 版本
方法上的文档标签@param 参数@return 返回值@throws 可能抛出@exception 异常描述@see 参考@inheritDoc
如何在 IDEA 配置 Javadoc 模板 ?Live Templates设置 Javadoc Template类的 Javadoc方法的 Javadoc
参考链接
什么是 Javadoc ？
Java 可以通过 Javadoc 将特定结构的注释从程序源代码中抽取出来形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。 为什么使用 Javadoc ？Javadoc 可以写在类或者方法上面，当其他开发人员使用了写了 Javadoc 的类或者方法时，仅通过鼠标悬停就可以获得该类或方法的使用说明，便于自己或其他人日后阅读程序。 Javadoc 的使用规范是什么样的 ？ 何时需要 Javadoc ？ 公开类、公开方法、受保护方法，需要其他模块或其他人员调用，应该书写 Javadoc私有方法及成员变量，若其命名已可概括其作用，则无需书写 Javadoc生成 html 文档时，私有成员的 Javadoc 会被忽略 Javadoc 结构概要描述 +详细描述+文档标签 概要描述：概要描述放在 Javadoc 的第一行，最好使用动宾短语，简短描述类的作用。通常鼠标悬停后，IDE 只会给出部分信息，所以尽可能准确而简短的概要说明非常必要， 详细描述：详细描述紧接概要描述并以一个空行来分割。对概要说明进行展开描述，若查阅者无法从概要说明中准确理解类的作用，则可进一步阅读详细说明。详细描述中可以使用html标签，Javadoc 注释中换行仅在卡片中表现为一个空格。 标签包含的内容上下自带换行，所以详细描述的段落都以 标签开始。 /** *This is a paragraph * describing how to use it */标签可定义预格式化的文本，可以在其中缩进、换行，但是内的仍会识别为标签，故通常配合{@code text}用于演示使用方法。 /** {@code * StringUtils.hasText(null) = false * } * /文档标签： a. 在类上 Javadoc 应标记作者、创建时间、参阅类等信息 b. 在方法上的 Javadoc 应标记参数、返回值、异常、参阅等 Javadoc 文档标签？ 类上的文档标签 @see 参考会创建一个文本为See Also的超链接，连接到其他类的文档说明，但javadoc不会检查链接是否有效 /** * @see fully-qulified-classname#method-name */ {@link target} 链接与@see 相似，但不是使用See Also作为超链接文本，而是使用“方法名” /** * 完全限定的类名 * {@link java.lang.Character} */ /** * 省略包名 * {@link String} */ /** * 省略类名，表示指向当前的某个方法 * {@link #length()} */ /** * 包名.类名.方法名(参数类型) * {@link java.lang.String#charAt(int)} */ @param 参数 /** * @param param-name description */@param 在类的 Javadoc 中对类的泛型参数进行说明 @param 在方法的 Javadoc 中为方法的参数进行说明 {@code text} 代码{@code text} 会被解析成 text 将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式 一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。 @author 作者详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author 后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址) @since 启用时间 /** * @since 16 April 2001 */ /** * @since 1.8 */放在类上，一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间 @version 版本 /** * @version 1.0 */@version 用于标记当前版本，默认为1.0 方法上的文档标签 @param 参数@param 后面跟参数名，再跟参数描述 /** * @param param-name description */ @return 返回值@return 后面跟返回值的描述 /** * @return description */ @throws 可能抛出@throws 后面跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常 /** * @throws fully-qualified-class-name description */fully-qualified-class-name是说这个方法会抛出哪个异常类 @exception 异常描述用于描述方法签名throws对应的异常 /** * @exception IllegalArgumentException if key is null. */ @see 参考@see 既可以用来类上也可以用在方法上，表示可以参考的类或者方法 @inheritDoc@inheritDoc 用于注解在重写方法或者子类上，用于继承父类中的Javadoc 基类的文档注释被继承到了子类子类可以再加入自己的注释（特殊化扩展）@return @param @throws 也会被继承 如何在 IDEA 配置 Javadoc 模板 ? Live Templates使用 IDEA 自带的 Live Templates 功能快速生成 Javadoc 模板，进入 Live Templates 的路径为： File->Settings->Editor->Live Templates 缩写设置为 cjd（class Javadoc） 这里选择 Java->declaration，即只在声明时触发 Template Text 中书写 /** * $description$ * @version 0.1.0 * @author zhishuai.liiu * @since 0.1.0 * @create $date$ $time$ **/设置变量 缩写设置为 fjd（Function Javadoc） 这里选择 Java->declaration，即只在声明时触发 Template Text 中书写 /** * $description$ * @param $param$ * @return $return$ * @author zhishuai.liu * @version 0.1.0 * @since 0.1.0 * @date $date$ $time$ */
Javadoc 使用详解：https://blog.csdn.net/vbirdbest/article/details/80296136 |
点击加号，添加一个 Template Group，命名为 Javadoc； 在 Javadoc 下，再点击加号，添加一个 Live Template，弹出下面这个操作面板； 
面板中 Abbreviation 是缩写，后面是 Description 是描述，Template Text 则是自动补全的内容。 Template Text 输入框下方，可以设置作用范围 
在 Template Text 中可以 通过$var$ 创建一个变量，在右侧的 Edit Variables 为变量绑定预设函数
【本文地址】