JBuilder2005建设开拓文档之编写注释
副标题#e#
5、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. }
#p#副标题#e#
在第8、19行添加上两个todo标签。todo标签可以放在措施的任那里所，而不象Javadoc标签一样必需安排在类、接口、要领等界说语句的前面。此时，这两个todo标签都将呈此刻布局窗格的To Do文件夹下，如下图所示：
图21 To Do文件夹
点击To Do文件夹下的项目，编辑器定位到代码中相应的位置。
假如你在工程的很多处所都插入了todo标签，如何查察检索查察它们呢？通过Search->View Todos，信息窗格中将列出工程中所有的todo标志，如下图所示：
图22 工程或工程组中所有todo标志
不单包括了todo的注释信息，功效列表中还列出了标志地址的措施文件及目次。你可以在Comment contains中输入要害字对todo标志的注释举办查询过滤。
3、自界说的Javadoc标签
JBuilder答允你为了实现非凡的用途自界说扩展的Javadoc标签。在这小节里，我们来界说一个名为notice的自界说标签。
1．Project->Project Properties…->Build->Javadoc，在Javadoc配置页中列出了所有自界说的Javadoc标签。由于todo标签是JBuilder自己自界说标签，所以todo呈此刻列表中，如下图所示：
图12 Javadoc自界说标签配置页
2．按New…按钮，弹出Create Custom Tag对话框，如下图所示：
图13 建设自界说Javadoc标签对话框
·Tag name：notice，标签名
·Heading Text：呈此刻Javadoc 文档中的标题。
·Placement options：选择所有的选项，暗示这个标签可以对代码中的任何范例元素举办注释。
3．按OK建设这个notice自界说标签。
打开Person.java用notice标签为sex值域写Javadoc注释：
1) /**@notice 这是用于暗示性此外变量，正当值只能为MALE和FEMALE*/
2) protected int sex;
对应的Javadoc文档如下图所示的文档：
图14 自界说Javadoc标签生成的文档
个中"留意"为Create Custom Tag对话框中的Heading text的内容，在上图中我们特地标识出来。
4、利用代码模板
在第4章中我们曾经先容过代码模板，你同样可觉得常用的注释块建设一个Javadoc模板，"多快好省"地录入Javadoc注释。
凭据习惯方法，每个类都需要一个类注释，类注释都是相似的，下面我们就来建设一个类注释代码模板，这个代码模板如下所示：
代码清单 2 类注释代码模板
1. /**
2. * <pre>|</pre>
3. * @see
4. * @version $Version, 2005-04-|
5. * @author $Author
6. * @since JDK1.3
7. */
#p#分页标题#e#
1) Tools->Perferences…->Editor->Templates->Common，点击Common配置页的Add…按钮，弹出New Code Template对话框，如下图所示：
图15 建设新代码模板对话框
·Template name：clscmt 模板的名字
·Description：class’s comment 模板描写信息
2) 在Code中录入代码清单 2的代码，个中带$前缀的标识是一个宏操纵符，在调解模板录入注释块后，宏将被替换成详细的值，你可以通过Macro…按钮，在Insert Macro对话框中选择一个宏，如下图所示：
图16 插入宏对话框
3) 录入代码模板后，按OK返回Common配置页，再按OK后完成建设clscmt代码模板。
建设完clscmt模板后，你就可以在编辑器顶用Ctrl+J挪用这个模板了，如下图所示：
图17 挪用clscmt代码模板
录入clscmt代码模板后，将发生一个类注释块，原$Author和$Version宏已经被替换成Project->Project Properties…->General配置页的class Javadoc fields列表中所配置的值了，如下图所示：
图18 用代码模板录入Javadoc注释块
此时，General配置页的class Javadoc fields列表的配置环境如下图所示：
图19 Javadoc域配置
