JBuilder2005创建开发文档之编写注释

JBuilder2005创建开发文档之编写注释2010-03-275、Javadoc注释冲突

Javadoc注释是对源码程序的说明，所以注释必须和源程序保持一致。假设一个方法共有两个入参，但对应的Javadoc仅对其中一个入参用@param进行了说明，两者出现了不一致，这时就出现了注释冲突。JBuilder能够检查出这种不一致的冲突，结构窗格树中将出现一个Javadoc Conflicts的文件夹，报告当前Java文件中所有的注释冲突，如下图所示：

图20 Javadoc冲突报告

每条冲突注释不但给出了冲突原因的简要描述，还指定了冲突发生的位置。你可以点击某冲突项，在弹出的对话框中选择Fix Javadoc Conflict for "XXX"修复这个冲突。你也可以右击Javadoc Conflicts文件夹，在弹出的菜单中选择Fix Javadoc Conflicts修复全部的冲突。

注意：

Javadoc冲突只有在Errors文件夹中所有的语法错误都已经得到解决后才会报告出来。

6、todo标签

todo是JBuilder自定义的标签，但它并不用于生成Javadoc文档的内容。它相当于一个"助记符"，表示此处有一个未完成的工作或一个待改进的工作，方便日后检索和处理这些未尽之事。

当前程序文件中的所有todo标签归结在结构窗格的To Do文件夹下。假设我们在Person.java中添加两个todo标签，如下所示：

1. …
2. public class Person implements Serializable
3. {
4.  public Person（String name ,int sex） throws PersonArgumentException
5.  {
6.   if（sex ！= MALE && sex ！= FEMALE）
7.    throw new PersonArgumentException（"参数不正确"）;
8.    /** @todo 还需做更多的校验 */
9.    this.name = name;
10.   this.sex = sex;
11. }
12.  …
13.  /**
14.  * 设置性别
15.  * @param sex int
16.  */
17.  public void setSex（int sex）
18.  {
19.   /** @todo 需要对入参做判断 */
20.   this.sex = sex;
21.  }
22. }