1、@author

该标记使用频率是所有文档标记中最高的，我想这是因为：

做好事要留名
使用超简单，就像在填表格（姓名：）一样自然

来看看大牛怎么写的：

javadoc标记

（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 吧）。

看看官网的标准解释：

javadoc标记

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）。比如别人在我们的文档注释中看到

javadoc标记

那他可以（应该）认为这个类是在该程序对外发布 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）分别表示：