4、使用代码模板
在第4章中我们曾经介绍过代码模板,你同样可以为常用的注释块创建一个Javadoc模板,"多快好省"地录入Javadoc注释。
按照习惯方式,每个类都需要一个类注释,类注释都是相似的,下面我们就来创建一个类注释代码模板,这个代码模板如下所示:
代码清单 2 类注释代码模板
1) Tools->Perferences...->Editor->Templates->Common,点击Common设置页的Add...按钮,弹出New Code Template对话框,如下图所示:
·Template name:clscmt 模板的名字
·Description:class’s comment 模板描述信息
2) 在Code中录入代码清单 2的代码,其中带$前缀的标识是一个宏操作符,在调整模板录入注释块后,宏将被替换成具体的值,你可以通过Macro...按钮,在Insert Macro对话框中选择一个宏,如下图所示:
3) 录入代码模板后,按OK返回Common设置页,再按OK后完成创建clscmt代码模板。
创建完clscmt模板后,你就可以在编辑器中用Ctrl+J调用这个模板了,如下图所示:
录入clscmt代码模板后,将产生一个类注释块,原$Author和$Version宏已经被替换成Project->Project Properties...->General设置页的class Javadoc fields列表中所设置的值了,如下图所示:
此时,General设置页的class Javadoc fields列表的设置情况如下图所示:
每条冲突注释不但给出了冲突原因的简要描述,还指定了冲突发生的位置。你可以点击某冲突项,在弹出的对话框中选择Fix Javadoc Conflict for "XXX"修复这个冲突。你也可以右击Javadoc Conflicts文件夹,在弹出的菜单中选择Fix Javadoc Conflicts修复全部的冲突。
注意:
Javadoc冲突只有在Errors文件夹中所有的语法错误都已经得到解决后才会报告出来。
6、todo标签
todo是JBuilder自定义的标签,但它并不用于生成Javadoc文档的内容。它相当于一个"助记符",表示此处有一个未完成的工作或一个待改进的工作,方便日后检索和处理这些未尽之事。
当前程序文件中的所有todo标签归结在结构窗格的To Do文件夹下。假设我们在Person.java中添加两个todo标签,如下所示:
在第8、19行添加上两个todo标签。todo标签可以放在程序的任何地方,而不象Javadoc标签一样必须放置在类、接口、方法等定义语句的前面。此时,这两个todo标签都将出现在结构窗格的To Do文件夹下,如下图所示:
点击To Do文件夹下的项目,编辑器定位到代码中相应的位置。
如果你在工程的许多地方都插入了todo标签,如何查看检索查看它们呢?通过Search->View Todos,信息窗格中将列出工程中所有的todo标记,如下图所示:
不但包含了todo的注释信息,结果列表中还列出了标记所在的程序文件及目录。你可以在Comment contains中输入关键字对todo标记的注释进行查询过滤。
在第4章中我们曾经介绍过代码模板,你同样可以为常用的注释块创建一个Javadoc模板,"多快好省"地录入Javadoc注释。
按照习惯方式,每个类都需要一个类注释,类注释都是相似的,下面我们就来创建一个类注释代码模板,这个代码模板如下所示:
代码清单 2 类注释代码模板
1. /** 2. * <pre>|</pre> 3. * @see 4. * @version $Version, 2005-04-| 5. * @author $Author 6. * @since JDK1.3 7. */ |
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注释块 |
图 19 Javadoc域设置 |
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. } |
在第8、19行添加上两个todo标签。todo标签可以放在程序的任何地方,而不象Javadoc标签一样必须放置在类、接口、方法等定义语句的前面。此时,这两个todo标签都将出现在结构窗格的To Do文件夹下,如下图所示:
图 21 To Do文件夹 |
点击To Do文件夹下的项目,编辑器定位到代码中相应的位置。
如果你在工程的许多地方都插入了todo标签,如何查看检索查看它们呢?通过Search->View Todos,信息窗格中将列出工程中所有的todo标记,如下图所示:
图 22 工程或工程组中所有todo标记 |
不但包含了todo的注释信息,结果列表中还列出了标记所在的程序文件及目录。你可以在Comment contains中输入关键字对todo标记的注释进行查询过滤。