分享
 
 
 

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

王朝other·作者佚名  2008-05-31
窄屏简体版  字體: |||超大  

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

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
2023年上半年GDP全球前十五强
 百态   2023-10-24
美众议院议长启动对拜登的弹劾调查
 百态   2023-09-13
上海、济南、武汉等多地出现不明坠落物
 探索   2023-09-06
印度或要将国名改为“巴拉特”
 百态   2023-09-06
男子为女友送行,买票不登机被捕
 百态   2023-08-20
手机地震预警功能怎么开?
 干货   2023-08-06
女子4年卖2套房花700多万做美容:不但没变美脸,面部还出现变形
 百态   2023-08-04
住户一楼被水淹 还冲来8头猪
 百态   2023-07-31
女子体内爬出大量瓜子状活虫
 百态   2023-07-25
地球连续35年收到神秘规律性信号,网友:不要回答!
 探索   2023-07-21
全球镓价格本周大涨27%
 探索   2023-07-09
钱都流向了那些不缺钱的人,苦都留给了能吃苦的人
 探索   2023-07-02
倩女手游刀客魅者强控制(强混乱强眩晕强睡眠)和对应控制抗性的关系
 百态   2020-08-20
美国5月9日最新疫情:美国确诊人数突破131万
 百态   2020-05-09
荷兰政府宣布将集体辞职
 干货   2020-04-30
倩女幽魂手游师徒任务情义春秋猜成语答案逍遥观:鹏程万里
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案神机营:射石饮羽
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案昆仑山:拔刀相助
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案天工阁:鬼斧神工
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案丝路古道:单枪匹马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:与虎谋皮
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:李代桃僵
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:指鹿为马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:小鸟依人
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:千金买邻
 干货   2019-11-12
 
推荐阅读
 
 
 
>>返回首頁<<
 
靜靜地坐在廢墟上,四周的荒凉一望無際,忽然覺得,淒涼也很美
© 2005- 王朝網路 版權所有