常用的Javadoc介绍

Javadoc标记

介绍常用的javadoc，全部javadoc可以见官网的 javadoc。

@author

用于标记代码的作者，可以用a标签将个人博客或个人邮箱与自己的姓名绑定。
另外，在 JDK 代码中我们经常看到 @author unascribed，意思是：“该代码第一原作者不是我，但我实在也不知道是谁，就记作无名氏吧”（这是多么严肃的一种版权意识啊）。

@value

可以用于生成被标记的常量字段的值。

{@inheritDoc}

继承父类的文档（包括@return @param @throws），子类可以再加入自己的注释。其实在不写 {@inheritDoc} 的情况下也存在文档注释的继承。

{@link}、{@linkplain}

link 和 linkplain 的实参都是package.class#member label。唯一的不同就是因为字体不同，如果 label 是个纯文本，那就使用 linkplain 吧。

@since

根据官方文档解释，@since 表达的是被标记元素是哪个发布版本引入的。

@version

提到了 @since 就自然会联想到 @version，因为它们的实参都是版本相关的。@version 要表达的是被标记元素自己的版本（注意对比 @since），也就是说这个版本只要代码改过就应该发生变化，而 @since 是不会变的。

@exception、@throws

它们完全是同义词，用于标记要抛出的异常。

@param @return @throws

标记参数，返回值，异常。

@deprecated

标记过时的方法或类。

HTML标记

pre

可以使用

来显示代码原有的样子，比javadoc的{@code }块好用多了，后者根本不能保证换行、缩进等，适合用于文中嵌入的代码。

当然还有一些常见的如 、

、
、 可以用于美化格式，就不一一指出了，反正javadoc都是支持的嘛。

其他

写中文注释的建议

• 使用中文的句号作为文档注释的结尾。
• 在中文中的英文和数字符号前后加入空格。

包注释

推荐使用 package-info.java 的方式，因为这样可以使用注解。

RESTful风格注解

如果需要为RESTful风格的接口书写文档的话，推荐使用apiDoc的规范，也可以生成html文档，着实好用，强力推荐

参考文章

• 细节见真功之 Javadoc
• javadoc - The Java API Documentation Generator