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

2024-07-21 02:15:15

字体：大中小

来源：转载

供稿：网友

　　可以通过代码模板快速的录入javadoc注释，你也可以选择通过javadoc对话框以一种形象化的方式录入javadoc注释。此外，jbuilder还提供了各种javadoc的辅助功能，如javadocinsight诱导录入，冲突报告和更正，特殊的todo标签等。

　　1、javadoc对话框

　　在编辑器中，将光标放在类、方法、值域等元素定义处右击，在弹出的菜单中选择add->javadoc for xxx将调出javadoc对话框。
打开person.java文件，将光标移到构造函数中，依照上述操作步骤调出javadoc对话框，如下图所示：

图 9 javadoc对话框

　　在description中列出了构造函数的描述信息，而tags中列出构造函数所有javadoc注释标签。你可以通过对话框右下角的按钮新增、编辑、删除标签，也可以调整它们的位置。

　　下面，我们为构造函数添加一个新的@see标签，链接到car.drive(int direction,int speed)函数中。

　　1．点击javadoc for constructor "person"对话框的add...按钮，弹出add javadoc tag对话框，如图 10所示。

　　2．从tag下拉框中选择see选项。

　　3．在description中录入javadoc.tool.car#drive(int,int)。

　　4．按ok返回javadoc for constructor "person"对话框，再按ok在编辑器中生成这个新的标签。

图 10 add javadoc tag对话框

　　实战经验：

　　虽然使用javadoc对话框可以以一种形象的方式创建javadoc注释，减少冲突概率，但由于需要在多个弹出的对话框中操作，且需要使用到键盘和鼠标，所以在键入速度和操作连贯性都很差。笔者在开发过程中几乎从未使用这种笨重的方法，既然是己所不欲，当然也不希望读者朋友使用。但初学者却可以通过javadoc对话框加强对javadoc标签的理解。

　　2、使用javadocinsight

　　象memberinsight、parameterinsight等一样，javadocinsight以诱导的方式辅助你快速录入正确的javadoc标签。

　　由于javadoc标签都带有@字符，当你录入@字符后javadocinsight诱导窗口自动弹出，延时时间可以通过tools->perferences...->editor->codeinsight设置页中调整，默认为250ms。一个典型的javadocinsight窗口如下图所示：

图 11 javadocinsight

　　在注释块中除可以用javadocinsight诱导窗口外，可以通过ctrl+space使用memberinsight诱导窗口录入类值域或方法，通过ctrl+alt+space使用classinsight录入类名。javadocinsight、memberinsight和classinsight有如三剑客，保证快速和正确地录入javadoc注释段。

　　提示：

　　javadocinsight窗口中除todo外都显示为粗体样式，todo标签不是javadoc标准的标签，而是jbuilder自定义的标签。jbuilder允许定义自定义的javadoc标签，所有自定义的javadoc标签显示为非粗体样式。关于自定义javadoc标签及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. */

　　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域设置

　　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标记的注释进行查询过滤。

　　提示：

　　一个工程性的软件项目，往往由于项目进度的紧迫，囿于时间和人力资源，你可能不得不舍弃一些好的解决方法而用一些易于实现的方法应急。你希望将来在允许的条件下再"重拾旧山河"，常言道，好记性不如烂笔头，如果在相应的地方用todo标签象武陵人从桃花源返回一样"处处志之"，就不会"遂迷不复得"了。

上一篇：JBuilder开发常用的十九个快捷键

下一篇：JBuilder2005创建开发文档之标签介绍