| |
JavaDoc，在 Java 的注释上做文章 |
|
时间: 2002-02-22 来自：yesky |
 |
|
二. 文档注释的格式
文档注释可以用于对类、属性、方法等进行说明。写文档注释时除了需要使用 /** .... */ 限定之外，还需要注意注释内部的一些细节问题。
1. 文档和文档注释的格式化
生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车符，而是写入 ＜br＞，如果要分段，就应该在段前写入 ＜p＞。
因此，格式化文档，就是在文档注释中添加相应的 HTML 标识。
文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如
编译输出后的 HTML 源码则是
This is first line. ＜br＞
This is second line. ＜br＞
This is third line. |
前导的 * 号允许连续使用多个，其效果和使用一个 * 号一样，但多个 * 号前不能有其它字符分隔，否则分隔符及后面的 * 号都将作为文档的内容。* 号在这里是作为左边界使用，如上例的第一行和第二行；如果没有前导的 * 号，则边界从第一个有效字符开始，而不包括前面的空格，如上例第三行。
还有一点需要说明，文档注释只说明紧接其后的类、属性或者方法。如下例：
/** comment for class */
public class Test {
/** comment for a attribute */
int number;
/** comment for a method */
public void myMethod() { ...... }
......
}
|
上例中的三处注释就是分别对类、属性和方法的文档注释。它们生成的文档分别是说明紧接其后的类、属性、方法的。“紧接”二字尤其重要，如果忽略了这一点，就很可能造成生成的文档错误。如
import java.lang.*;
/** commnet for class */
public class Test { ...... }
// 此例为正确的例子
|
这个文档注释将生成正确的文档。但只需要改变其中两行的位置，变成下例，就会出错：
/** commnet for class */
import java.lang.*;
public class Test { ...... }
// 此例为错误的例子
|
这个例子只把上例的 import 语句和文档注释部分交换了位置，结果却大不相同——生成的文档中根本就找不到上述注释的内容了。原因何在？
“/** commnet for class */”是对 class Test 的说明，把它放在“public class Test { ...... }”之前时，其后紧接着 class Test，符合规则，所以生成的文档正确。但是把它和“import java.lang.*;”调换了位置后，其后紧接的就是不 class Test 了，而是一个 import 语句。由于文档注释只能说明类、属性和方法，import 语句不在此列，所以这个文档注释就被当作错误说明省略掉了。
|
|
|
|
|
|
|
|
