修炼系列（八），你真的会写注释吗

本节主要介绍下我们常用的 javadoc tag ，虽然内容比较简单，但若正确使用，真的能使我们的代码高大上不少。不仅如此，只要我们按照Javadoc 注释规则，在编码完成后，Javadoc 也能够帮我们从源代码中生成相应的 Html 格式的 API 开发文档。可以点击Oracle规范，我将常用的javadoc tag 根据自己的习惯进行了整理，见下：

tags

在给公共类或公共方法添加注释的时候，第一句话应该是一个简短的摘要。注意左侧不要紧挨 * 号，要有一个空格。如果注释有多个段落，使用< p>段落标记来分隔段落。我们还可使用< tt>标签来让特定的内容呈现出等宽的文本效果。见下：

    /*** 第一句话是这个方法的<tt>简短</tt>摘要。* 如果这个描述太长，记得换行。* * <p>如果多个段落可以这样* 当回车的时候与标签首部对齐即可*/public void test(){}
复制代码

如果注释描述里需要包含一个列表，一组选项等，我们可以使用< li>标签来标识，注意标签后不需要空格，见下：

    /*** 第一句话是这个方法的简短摘要。* 如果这个描述太长，记得换行。* * <p>如果多个段落可以这样* * <ul>* <li>这是列表1* <li>这是列表2...* 同样回车后与标签对齐即可* </ul>*/public void test(){}
复制代码

@param 是用来描述方法的输入参数。注意在方法描述和tag 之间需要插入空白注释行。不需要每个参数param的描述都对齐，但要保证同个param的多行描述对齐。param 的描述不需要在句尾加标点。

    /*** 第一句话是这个方法的简短摘要。* 如果这个描述太长，记得换行。** @param builderTest 添加参数的描述，如果描述很长，*                    需要回车，这里需要对齐* @param isTest 添加参数描述，不需要刻意与其他param*               参数对齐*/public void test(String builderTest, boolean isTest){}
复制代码

@return 是用来描述方法的返回值。要写在@param tag之后，与其他tag 之间不需要换行。@throws 是对方法可能会抛出的异常来进行说明的，通常格式为：异常类名+异常在方法中出现的原因。见下：

    /*** 第一句话是这个方法的简短摘要。** @param capacity 添加参数描述，不需要刻意与其他param*                 参数对齐* @return 描述返回值的含义，可以多行，不需要句号结尾* @throws IllegalArgumentException 如果初始容量为负*         <ul>*         <li>这是抛出异常的条件1（非必须），注意<li>格式*         </ul>* @throws 注意如果方法还存在其他异常，可并列多个*/public int test(int capacity){if (capacity < 0)throw new IllegalArgumentException("Illegal initial capacity");return capacity;}
复制代码

@deprecated 用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用旧特性。常与@link 配合，当然@link的使用位置没有任何限制，当我们的描述需要涉及到其他类或方法时，我们就可以使用@link啦，javadoc会帮我们生成超链接：

    /*** 第一句话是这个方法的简短摘要。* 如果这个描述太长，记得换行。* * @deprecated 从2.0版本起不推荐使用，替换为{@link #Test2()}* @param isTest 添加参数描述，不需要刻意与其他param*               参数对齐*/public void test(boolean isTest){}
复制代码

@link 常见形式见下:

@code 用来标记一小段等宽字体，也可以用来标记某个类或方法，但不会生成超链接。常与@link配合，首次通过@link生成超链接，之后通过@code 呈现等宽字体。

    /*** 第一句话是这个方法的简短摘要。* 我们可以关联{@link Test}类，随后通过{@code Test}类怎样怎样* 也可以标记一个方法{@code request()}** @param isTest 添加参数描述，不需要刻意与其他param*               参数对齐*/public void test(boolean isTest){}
复制代码

@see 用来引用其它类的文档，相当于超链接，javadoc会在其生成的HTML文件中，将@see标签链到其他的文档上：

    /*** 第一句话是这个方法的简短摘要。** @param capacity 添加参数描述，不需要刻意与其他param*                 参数对齐* @return 描述返回值的含义，可以多行，不需要句号结尾* @throws IllegalArgumentException 如果初始容量为负* @see com.te.Test2* @see #test(int)*/public int test(int capacity){if (capacity < 0)throw new IllegalArgumentException("Illegal initial capacity");return capacity;}
复制代码

@see形式与@link类似，见下：

@since 用来指定方法或类最早使用的版本。在标记类时，常与@version和@author配合，一个用来指定当前版本和版本的说明信息，一个用来指定编写类的作者和联系信息等。我们也可以通过< pre>来添加一段代码示例。见下：

    /*** 第一句话是这个类的简短摘要。* <pre>*     Test<Test2> t = new Test<>();* </pre>* * <p>同样可以多个段落。* * @param <T> 注意当类使用泛型时，我们需要使用params说明。这时格式需要插入空白行** @author mjzuo 123@qq.com* @see com.te.Test2* @version 2.1* @since 2.0*/public class Test<T extends Test2> {/*** 第一句话是这个方法的简短摘要。* * @params capacity 参数的描述* @return 返回值的描述* @since 2.1*/public int test2(int capacity) {return capacity;}}
复制代码

@inheritDoc 用来从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。如下的test() 方法，会直接继承该类的直接父类的test()方法注释。注意与其他tag 不需要插入空行：

    /*** {@inheritDoc}* @since 2.0*/public void test(boolean isTest){}
复制代码

@docRoot 它总是指向文档的根目录，表示从任何生成的页面到生成的文档根目录的相对路径。例如我们可以在每个生成的文档页面都加上版权链接，假设我们的版权页面copyright.html 在根目录下：

    /*** <a href="{@docRoot}/copyright.html">Copyright</a>*/public class Test {}
复制代码

@hide 当我们使用google提供的Doclava时，可以使用 @hide 来屏蔽我们不想暴露在javaDoc文档中的方法。

    /*** {@hide}*/public class Test {}
复制代码

好了，本文到这里，关于常用的javaDoc tag的介绍就结束了，希望本文对你有用。

作者：Zuo
链接：https://juejin.cn/post/6946028736693305352
来源：稀土掘金
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

修炼系列（八），你真的会写注释吗相关推荐

优秀的程序员真的不写注释吗？ | 原力计划
作者 | 沉默王二责编 | 王晓曼出品 | CSDN博客前言我在很多地方看到这样一个观点,"请停止写注释,因为只有烂的代码才需要注释."这个观点非常巧妙,它让我想起了孟子的 ...
sed修炼系列(四)：sed中的疑难杂症
sed系列文章: sed修炼系列(一):花拳绣腿之入门篇 sed修炼系列(二):武功心法(info sed翻译+注解) sed修炼系列(三):sed高级应用之实现窗口滑动技术 sed修炼系列(四):s ...
数学之美系列八-- 贾里尼克的故事和现代语言处理
数学之美系列八-- 贾里尼克的故事和现代语言处理读者也许注意到了,我们在前面的系列中多次提到了贾里尼克这个名字.事实上,现代语音识别和自然语言处理确实是和它的名字是紧密联系在一起的.我想在这回的系 ...
sed修炼系列(三)：sed高级应用之实现窗口滑动技术
sed系列文章: sed修炼系列(一):花拳绣腿之入门篇 sed修炼系列(二):武功心法(info sed翻译+注解) sed修炼系列(三):sed高级应用之实现窗口滑动技术 sed修炼系列(四):s ...
sed修炼系列(一)：花拳绣腿之入门篇
本文目录: 1 基本概念 2 sed选项 3 定址表达式 4 sed常用命令 5 总结 1.基本概念 sed是一个流式编辑器程序,它读取输入流(可以是文件.标准输入)的每一行放进模式空间(patter ...
PGL图学习之图神经网络ERNIESage、UniMP进阶模型[系列八]
PGL图学习之图神经网络ERNIESage.UniMP进阶模型[系列八] 原项目链接:fork一下即可:https://aistudio.baidu.com/aistudio/projectdetai ...
数据与广告系列八：广告与二类电商
作者|黄崇远(题图:pixabay.com,CCO协议) 距上一篇<数据与广告系列七:广告与推荐系统技术架构>已经快有一个半月了.这一个月多里,确实很忙,五月底出去溜了一圈,六月初新的工作 ...
Android音视频学习系列(八) — 基于Nginx搭建(rtmp、http)直播服务器
系列文章 Android音视频学习系列(一) - JNI从入门到精通 Android音视频学习系列(二) - 交叉编译动态库.静态库的入门 Android音视频学习系列(三) - Shell脚本入门 ...
JAVA面试常考系列八
转载自 JAVA面试常考系列八题目一 JDBC是什么? JDBC(Java DataBase Connectivity,java数据库连接)是一种用于执行SQL语句的Java API,可以为多种关系 ...

修炼系列（八），你真的会写注释吗

tags

修炼系列（八），你真的会写注释吗相关推荐

最新文章

热门文章