如何写出格式优美的javadoc？

如果你读过Java源码，那你应该已经见到了源码中优美的javadoc。在eclipse 中鼠标指向任何的公有方法都会显示出详细的描述，例如返回值、作用、异常类型等等。

本文主要来自《Thinking in java》的内容以及我在工作中写javadoc的经验。

三种类型的注释文档

注释文档有三种类型，分别对应于注释位置后面的三种元素：类、域和方法。也就说类注释正好位于类定义之前；域注释位于域定义之前；方法注释位于方法定义之前。如图所示：

//: object/Documentation1.java
/** 类注释 */
public class Documentation1 {
    /** 域注释 */
    public int i;
    /** 方法注释 */
    public void f() {}
} ///:~

注意，javadoc只能为public 和protected 成员进行文档注释。private 和包内可访问成员的注释会被忽略掉，所以在输出结果中看不到他们。如果想在输出结果中查看可以使用 -private 进行标记。这样做是因为只有公用的和受保护的成员才能在文件之外被使用。上述代码生成的HTML文档可以在浏览器中查看。

嵌入式HTML

javadoc通过生成的html文档传送HTML命令，这使你能充分利用HTML。

/**
* <pre>
* System.out.println(new date())
* </pre>
*/
///:~

从上述注释中我们也能看出，注释是会进行输出的，所以才会有System.out.println(new date()) 这个代码。

还可以用HTML代码格式化注释：

/**
* You can <em>even</em> insert a list:
* <ol>
* <li> item one
* <li> item two
* <li> item three
* </ol>
*/
///:~

注意，每一行星号以及之后的空格内容不会输出到文档中，另外也不要在javadoc中使用标题标签，例如<h1>或者<hr>。这是因为javadoc会插入自己的标题，而你的标题可能同它们发生冲突。

javadoc标签

1.@see：引用其他类

@see 标签允许用户引用其他类的文档。javadoc会在其生成的HTML文件中，通过@see 标签链接到其他文档。格式如下：

@see 类名
@see 完整类名
@see 完整类名#方法名

每一格式都会在生成的文档里自动加入一个超链接的“See Also”（参见）条目。注意javadoc不会检查我们指定的超链接，不会验证它们是否有效。

2.{ @link package.class#member label }

该标签与@see极其相似，只是它用于行内，并且是用“label” 作为超链接文本而不用“See Also”。

3.{ @docRoot }

该标签产生到文档根目录的相对路径，用于文档树页面的显示超链接

4.{ @inheritDoc }

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5. @version

格式如下：

@version version-information

其中，“version-information”代表任何适合作为版本说明的资料。若在javadoc命令行使用了“-version”标记，就会从生成的HTML文档里提取出版本信息。

6. @author

格式如下：

@author author-information

其中，“author-information”包括您的姓名、电子函件地址或者其他任何适宜的资料。若在javadoc命令行使用了“-author”标记，就会专门从生成的HTML文档里提取出作者信息。

可为一系列作者使用多个这样的标记，但它们必须连续放置。全部作者信息会一起存入最终HTML代码的单独一个段落里。

7. @since

该标签允许你指定程序代码的最早使用版本，可以在HTML java文档中看到它被用来指定所用的JDK版本的情况。

8. @param

该标签用于方法文档中，行使如下：

 @param parameter-name description

其中，“parameter-name”是指参数列表内的标识符，而“description”代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记，就认为前一个说明结束。可使用任意数量的说明，每个参数一个。

9. @return

格式如下：

@return description

其中，“description”是指返回值的含义。它可延续到后面的行内。

10. @throws

格式如下：

@throws fully-qualified-class-name description

其中fully-qualified-class-name description给出一个异常类的无歧义的名字，而该异常类在别处定义。description告诉你为什么此特殊类型的异常会在方法调用中出现。

11.@Deprecated

该标签用于之处一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来它们很可能会被删除。如果使用一个标记为@Deprecated的方法，则会引起编译器发布警告。

源码示例

我们看看JDK8中equals方法的注释是怎样写的：

/**
     * Compares this string to the specified object.  The result is {@code
     * true} if and only if the argument is not {@code null} and is a {@code
     * String} object that represents the same sequence of characters as this
     * object.
     *
     * @param  anObject
     *         The object to compare this {@code String} against
     *
     * @return  {@code true} if the given object represents a {@code String}
     *          equivalent to this string, {@code false} otherwise
     *
     * @see  #compareTo(String)
     * @see  #equalsIgnoreCase(String)
     */
    public boolean equals(Object anObject) {
        if (this == anObject) {
            return true;
        }
        if (anObject instanceof String) {
            String anotherString = (String)anObject;
            int n = value.length;
            if (n == anotherString.value.length) {
                char v1[] = value;
                char v2[] = anotherString.value;
                int i = 0;
                while (n-- != 0) {
                    if (v1[i] != v2[i])
                        return false;
                    i++;
                }
                return true;
            }
        }
        return false;
    }

再来看下在eclipse中的显示效果。

{@code } 前面没有介绍过，实际显示效果很容易看出来，就是把空格后的内容显示成代码的样式。

写出言简意赅，便于维护的注释需要长期的练习。除了工作中有意识的使用javadoc以外，阅读源码，模仿源码注释的写法也是不错的选择。