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

核心提示：可以通过代码模板快速的录入javadoc注释，你也可以选择通过Javadoc对话框以一种形象化的方式录入Javadoc注释，JBuilder2005创建开发文档之编写注释，此外，JBuilder还提供了各种Javadoc的辅助功能，如下图所示：图 21 To Do文件夹点击To Do文件夹下的项目，编辑器定位到代码中相

　　可以通过代码模板快速的录入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标签，如何查看检索查看它们呢？