javadoc标记

参考：

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 一样）。但问题是大家写的时候表达的意思五花八门，常见的有：

1. 想表达日期/时间
   @since 2014-01-01
   @since 2014-01-01 14:00:00
2. 想表达可运行的 JDK 版本
   @since JDK1.5
3. 想表达加入这个元素的版本
   @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 也会被继承

13、pre

没错，这就是那个 HTML 标签，用于显示“原始样子”的。这个标签在写 Javadoc 的时候非常有用，用或者不使用在打码的时候看上去差别不大：

但最终生成 apidocs 之后差别一目了然（处女座阅读提示：在源码文档注释中特别需要注意 pre 后 { 的位置，紧跟 *，无空格）：

14、{@literal} {@code}

类似于xml的cdata，可以把html特殊符号显示出来而不需要使用实体,例如<两者只是显示的字体不一样而已，用法一样

{@literal txt}