参考:
http://symphony.b3log.org/article/1402537988442
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
1、@author
该标记使用频率是所有文档标记中最高的,我想这是因为:
- 做好事要留名
- 使用超简单,就像在填表格(姓名: )一样自然
来看看大牛怎么写的:
(from Commons Lang 2.5 StringUtils)
总结下来有三种写法:
- 纯文本
- 带邮箱链接
- 带 HTTP 链接
(个人建议用 HTTP 链接:打码时可以顺便推广一下自己的博客,哈哈)
另外,在 JDK 代码中我们经常看到 @authorunascribed,意思是:“该代码第一原作者不是我,但我实在也不知道是谁,就记作无名氏吧”(这是多么严肃的一种版权意识啊)
2、{@docRoot}
代表产生文档的根路径
@see <a href={@docRoot}/xxx.html>xxx</a>
3、@deprecated
deprecated-text 添加注释,表明已过时
@deprecated xxx
4、@exception @throws
这两兄弟的情况比 @link @linkplain 更纠结(人家 link 兄弟最起码可以区分出来使用场景)。按照官方文档解释:它们完全是同义词,没有任何区分。那当年 Sun 在 JDK1.2 的时候为什么要加入 @throws 呢——答案是起名失误了,词性没弄匹配:@throws Exception 比 @exception Exception 更符合语法,代入感更好!(细节:In javadoc, what is the difference between the tags @throws and @exception?)
5、@see
添加"参见"标题,其中有指向reference的链接或者文本项,@see标记有三种形式,下面分别说明:
@see "string" 为"string"添加文本项,不产生链接。
@see <a href="URL#Value">Label</a> 使用HTML标记产生链接
@see package.class#member Label 使用Java语言的名字package.class #member产生链接。
6、{@link} {@linkplain}
这两个链接标记大家用/见的应该比较多,但它们有什么区别、在什么场景下该怎么使用很少有人能够区分开(我猜你要用的时候一般也都是用 link 吧)。
看看官网的标准解释:
link 和 linkplain 的实参都是 package.class#member label 。唯一的不同就是因为字体不同,如果 label 是个纯文本,那就使用 linkplain 吧。(根据这点,我严重怀疑 Javadoc 文档标记的设计者是处女座,~ ~)
7、@param
描述参数
8、 @return
描述返回值
9、@since
这个从字面的意思上很好理解,所以使用的比较多(如同 @author、@version 一样)。但问题是大家写的时候表达的意思五花八门,常见的有:
- 想表达日期/时间
@since 2014-01-01
@since 2014-01-01 14:00:00 - 想表达可运行的 JDK 版本
@since JDK1.5 - 想表达加入这个元素的版本
@since 1.0.0
根据官方文档解释,@since 表达的是被标记元素是哪个发布版本引入的(3)。比如别人在我们的文档注释中看到
那他可以(应该)认为这个类是在该程序对外发布 1.0.0 版本时已经引入的。如果他要做二次开发,那他就可以很清晰的向后兼容了(我们在用 JDK 的时候就是这个场景)。
10、@version
提到了 @since 就自然会联想到 @version,因为它们的实参都是版本相关的。@version 要表达的是被标记元素自己的版本(注意对比 @since),也就是说这个版本只要代码改过就应该发生变化,而 @since 是不会变的。
官方文档也解释了怎么用好这个文档标记:通过 SCCS 字符 "%I%, %G%",例如 1.39, 02/28/97(文件版本号, 日期)生成。但实际上很少有项目这么做(至少目前 Oracle JDK 没这么做,甚至都没有使用 @version,或者是使用了但最后由于特殊原因总体移除了),大家一般都是 @version 1.0.0 然后就再也不修改了,不管被标记的元素改了多少次(这样的做法还不如不写)。
当然,通过版本控制系统 hook 来做是比较经典的做法,不过这样总感觉没有把这个标记的能力完全发挥出来。在我们的项目里是这样使用的:@version 1.2.3.4, Jun 9, 2014
重点是版本号部分,在这个例子中从左到右(1.2.3.4)分别表示:
- 兼容性位 1,表示兼容性,如果 +1 了说明这个修改是不兼容的
- 特性位 2,表示已引入了两个特性,每次 +1 说明引入一个新特性
- 缺陷修复位 3,表示已经修复了 3 个缺陷,每次 +1 说明修复了一个缺陷
- 重构位 4,表示已经进行了 4 次重构,每次 +1 说明重构了一次
前面 3 位表达的意义和Semantic Versioning建议的一致,重构我觉得非常重要,所以也加了进来。
11、@value
这个文档标记非常实用(不光好用),可以用于生成被标记的常量字段的值。
直接用于常量字段时:
也可以使用引用方式:
12、{@inheritDoc}
这个标签体现了 Java 面向对象的精辟所在:不但可以类可以集成,连文档都可以继承(足见 Java 在经典面向对象概念上的完备与圆润)。
比如有个计算面积的接口:
它的实现方法标注了 {@inheritDoc}(处女座阅读提示:无 .):
最后生成的文档:
- 基类的文档注释被继承到了子类
- 子类可以再加入自己的注释(特殊化扩展)
- @return @param @throws 也会被继承