[转载]JBuilder2005创建开发文档之编写注释
可以通过代码模板快速的录入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. * | 3. * @see |
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标签象武陵人从桃花源返回一样" 处处志之",就不会"遂迷不复得"了。 |
来自 “ ITPUB博客 ” ,链接:http://blog.itpub.net/374079/viewspace-131367/,如需转载,请注明出处,否则将追究法律责任。
转载于:http://blog.itpub.net/374079/viewspace-131367/
[转载]JBuilder2005创建开发文档之编写注释相关推荐
- 开发文档怎么编写_PoC 编写指南
什么是 PoC PoC(全称: Proof of Concept), 中文译作概念验证.在安全界,你可以理解成为漏洞验证程序.和一些应用程序相比,PoC 是一段不完整的程序,仅仅是为了证明提出者的观点 ...
- python软件开发-如何编写Python软件开发文档(7个技巧)
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
- Android官方开发文档Training系列课程中文版:创建自定义View之View的创建
原文地址:http://android.xsoftlab.net/training/custom-views/index.html 引言 Android框架含有大量的View类,这些类用来显示各式各样 ...
- Android官方开发文档Training系列课程中文版:使用Fragment构建动态UI之Fragment创建
原文地址:http://android.xsoftlab.net/training/basics/fragments/index.html 导言 为了在Android中创建动态的多面板用户界面,你需要 ...
- python开发软件的实例-如何编写Python软件开发文档(7个技巧)
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
- 敏捷开发:编写开发文档的利与弊
敏捷开发学习总结: 思考开发文档的利与弊 文档是个好东西,这是不可否认的,但是太依赖文档也有弊端,下面我从不同的度来分析一下文档的利与弊,然后思考在敏捷开发时,文档又是如何进行的. 从 公司的角度来看 ...
- python写软件实例-如何编写Python软件开发文档(7个技巧)
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
- 开源轻量级办公系统Sandbox介绍以及配套开发文档连载
1.Sandbox介绍 Sandbox是一个基于django框架开发的轻量级办公平台,主要模块有:权限控制.资产(库存)管理.设备管理.客户信息管理和工单流程管理,其目的在于建立一套规范化.统一化和清 ...
- .NET6使用DOCFX根据注释自动生成开发文档
本文内容来自我写的开源电子书<WoW C#>,现在正在编写中,可以去WOW-Csharp/学习路径总结.md at master · sogeisetsu/WOW-Csharp (gith ...
最新文章
- wxpython dataview处理大量数据_38个常用Python库:数值计算、可视化、机器学习等8大领域都有了...
- python项目归纳总结-这4个Python实战项目,让你瞬间读懂Python!
- C++读写EXCEL文件方式比较 .
- Android 7.1.1 锁屏界面启动流程
- Java_案例实例2.约瑟夫环问题
- 服务器上的hdfs的配置文件中,namenode不能设置成127.0.0.1或者localhost,要设置ip或者映射别名
- 模块降额设计_模块电源需要注意的四个点
- js/d3.min.js_在5分钟内学习D3.js
- 《Android开发艺术探索》读书笔记 (4) 第4章 View的工作原理
- 你可能没听过的11个Python库,你有认识的吗?
- Spring Cloud Ribbon 负载均衡客户端调用示例
- scala中的特殊字符
- Deepracer 学了就能云驾驭赛车? Deepracer机器学习进阶版干货分享!
- 《Python核心编程》第二版第三版高清PDF 中文
- 复习,网课,视频回放,太慢怎么办,试试倍速播放吧 (无需下载)
- 六年级上学期计算机上册教案,最新人教版六年级上册数学全册教案
- 用户画像——《大数据用户画像的方法及营销实践》演讲
- 高中3年,3500个词汇带音标,归成“图表”
- Java实现 蓝桥杯算法提高金明的预算方案
- java excel 饼图_Java 在 Excel 中创建饼图/环形图
热门文章
- 1.9 项目的特征——案例:三峡工程
- (转)什么是AQS??
- 马蜂窝 IM 系统架构的演化和升级
- 用HTTP proxy module配置一个简单反向代理服务器
- 【学习python】re 正则表达式匹配特定词性的conll,提取句子主干(主谓宾)
- K210 图像识别 (加训练模型)
- 验证码与银行卡冻结计时系统
- c语言void* arg,求教!!!void *(*process) (void *arg);
- 当今粤语懒音现象大观
- VMware UBUNTU su 认证失败