JBuilder2005创建开发文档之编写注释 - 编程入门网

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

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. }

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

在第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自定义标签设置页

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

2．按New...按钮，弹出Create Custom Tag对话框，如下图所示：

图13 创建自定义Javadoc标签对话框

·Tag name：notice，标签名

·Heading Text：出现在Javadoc 文档中的标题。

·Placement options：选择所有的选项，表示这个标签可以对代码中的任何类型元素进行注释。

3．按OK创建这个notice自定义标签。

打开Person.java用notice标签为sex值域

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!