如何写出格式优美的javadoc?

澳门新葡亰手机版 1

文档注释

文档注释是一种与多行注释很类似的特殊注释,它可以用来为你的源代码产生外部文档。这种注释以紧跟着两个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。例如:

/** This is a documentation comment */

/** This is also a

    documentation comment */

这里有一些关于文档注释的重要事情要注意:

  • javadoc文档生成器会把文档注释里的所有文本都添加到一个HTML段落里。这意味着,在文档注释里的任意文本都会被格式化为一个段落;空格和换行符会被忽略。如果你想要特殊的格式,你必须要在文档注释里使用HTML标签。

  • 如果文档注释以超过两个的星号开始,那么javadoc就认为这些星号是用来在源码里创建一个“框”框住注释的,并忽略多余的星号。例如:

/**********************************

   This is the start of a method

**********************************/

该注释仅保留“This is the start of a method”文本。

  • 澳门新葡亰手机版,javadoc会忽略文档注释里处于行首的星号。例如:

/***************************************

 * This is a doc comment

 * on multiple lines that I want to stand

 * out in source code, looking "neat"

 ***************************************/

该注释仅保留“This is a doc comment on multiple lines that I want to
stand out in source code, looking “neat””文本。

  • 常见的用法如下:

/******************************************

   ...

 ******************************************/

该用法是为了突出注释。要注意的是,这属于文档注释(即使这不是你所想的那样),并会在产生的文档里出现注释的内容。

源码示例

我们看看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中的显示效果。

澳门新葡亰手机版 1

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

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

什么时候使用单行注释

任意时候都可以!

关于注释,我有一个简单的建议,在你想写常规注释(不是用来描述类、接口、方法或者变量的文档注释)的时候可以使用单行注释。

为什么?因为你可以轻易地使用多行注释去“注释掉”你的代码段(“注释掉代码”意味着把一段代码的词法状态变为一段注释,让编译器忽略这段代码)。举个例子:

x = 1;   /* set x to 1 */

y = 2;   /* set y to 2 */

f(x, y); /* call f with x and y */

要把上面三行代码注释掉,你可能需要在每一行的前面使用单行注释:

// x = 1;   /* set x to 1 */

// y = 2;   /* set y to 2 */

// f(x, y); /* call f with x and y */

或者在还没有加注释的地方加上多行注释:

/* x = 1;  */ /* set x to 1 */

/* y = 2;  */ /* set y to 2 */

/* f(x, y);*/ /* call f with x and y */

或者分解或删除已存在的注释的“结束注释”分解符:

/*

x = 1;   /* set x to 1 * /

y = 2;   /* set y to 2 * /

f(x, y); /* call f with x and y * /

*/

这些用法都糟糕透了。如果原始代码使用下面的注释,那么事情就好办多了:

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

如此一来,只需使用多行注释把代码围起来你就可以轻松把它注释掉:

/*

x = 1;   // set x to 1

y = 2;   // set y to 2

f(x, y); // call f with x and y

*/

在你需要使用注释的时候尽量使用单行注释,不要写无用的注释。

你也可以看看之前发布的9个最有趣的代码注释,尽管它是搞笑的。

嵌入式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>或者


。这是因为javadoc会插入自己的标题,而你的标题可能同它们发生冲突。

单行注释(C++风格)

在Java中最简单的注释是单行注释。它以两个正斜杠开始并到行尾结束。例如:

// this is a single-line comment

x = 1; // a single-line comment after code

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

多行注释(C风格)

Java同样提供跨越多行的注释类型。这种类型的注释以紧跟着一个星号的正斜杠开始,并以紧跟着一个正斜杠的星号结束。这种类型注释的开始和结束分界符可以在同一行里也可以在不同的行上。例如:

/* This is a c-style comment */

/*  This is also a

    c-style comment, spanning

    multiple lines */

注意:C风格的注释不可以嵌套使用。比如下面的用法:

/* A comment looks like

   /* This is a comment */

   blah blah blah

 */

上面的用法会造成语法错误,因为Java编译器只把第一个 */
当做注释来处理。(编译器认为注释在第一个“*/”就结束了)。

你可以在多行注释里嵌入单行注释:

/* This is a single-line comment:

    // a single-line comment

 */

以及在单行注释里使用多行注释:

// /* this is

//    a multi-line

//    comment */

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