Jautodoc是一款Eclipse插件,主要用于在源代码文件中自动添加Javadoc和文件头.它使用Velocity templates模板,并依据元素名生成相应的注释.
特性
Jautodoc主要有以下特性:
1. 模式
补全已有Javadoc:已经存在的Javadoc不会被修改或覆盖.只会补充遗漏的标签以及还没有文档化的元素;
保持已有Javadoc:已经存在的Javadoc不会被修改或覆盖.遗漏的标签不会补充,但是会文档化之前未文档化的元素;
替换已有Javadoc:已有Javadoc将由生成的Javadoc全部替换掉.注意谨慎使用这一选项.
2. 可见性
- Public, protected, package 或者 private
可以限定相应可见性层次的属性能创建Javadoc.
3.过滤器
- 注释Types, Fields, Methods 或者Getter/Setter only
可以决定那种类型的类成员可以创建Javadoc.
4.选项
- 为自动生成的Javadoc添加ToDo标记
目的是便于找到包含自动生成Javadoc的所有源文件。每个源文件中只生成一次。
依据元素名创建注释
设置这个选项后Jautodoc将如下所示依据元素名生成注释。模板可以定义生成格式，生成方式。另外，对于方法，字段，参数缩写在”替换”中将定义。
字段:
方法：
单行字段注释：
创建单行注释的选项.
使用Eclipse的注释格式化
可以使用Eclipse自带的格式化工具对生成的注释进行格式化。可以在preferences中设置相应的格式样式：
字段的getter/setter注释
依据字段注释创建Getter/Setter注释
文件头
- 添加/替换文件头
如果还没有文件头的话，你可以定义一个文件头添加到源文件中。你可以选择将已有文件头替换掉。勾选上“多注释文件头”，则源文件开头的多个注释能被替换掉。在文件头文本中可以使用Velocity Template Language (VTL)
and预定义变量。
注意：为了在文件头模板内部使用美元符号（例如SVN/CVS属性$id$），你需要使用转义字符对其进行转义(\$)。
Package Javadoc
- 编辑模板
你可以为package.html或者package-info.java定义初始内容。可以通过在Package Explorer 视图中选择相应包节点右键，选择Add Package Javadoc。
· 同文件头注释一样，可以在模板中使用Velocity Template Language (VTL)和预定义变量.
- 使用package-info.java
使用package-info.java代替package.html
替换
当根据元素名创建注释时，可以使用另一文本代替方法，字段，参数中的一部分。例如”set”将被”Sets the”替换，”db”将被扩展为”Database”等。
通过preferences可以添加、删除、更改这些替换方式。替换范围可以是字段、方法或者两者。使用字段范围时对字段和参数都适用。默认情况下只有前缀或者出现缩略词时会替换。
注意:缩略词是不区分大小写的。 Shortcuts are case insensitive. 它们通过单词首字母大写的方式检测出间隔 (比如setDbName).
- 对于打开的源文件Javadoc可以为所有的或者指定的成员添加注释。在这种情况下，修改的元文件不会自动保存到硬盘中。
如果光标位于字段或者方法声明的内部，则只有这个元素可以文档化。If the cursor is inside the declaration of an field or method, only this element will be documented. 要创建一个类型注释指向类型名字。否则目前源文件的所有成员都会被文档化。
· 选择带有 "..."的菜单项将会打开选项对话框，这里面可以重写设置新的规则覆盖掉之前的相关设置。这些设置只对当前编译单元有效，且只针对于该Eclipse会话。
- 在Package Explorer视图模式下你可以选择一个或者多个源文件来添加Javadoc。you can select one or more source file(s) in order to add Javadoc.或者，你可以选择一个包，为该包中的所有成员添加Javadoc，或者你也可以针对整个项目使用。
警告: 没有在编辑器中被打开的源文件将会直接被存进磁盘中。
当使用选项对话框时，你可以预览所有的更改。
任务搜索
Jautodoc允许使用搜寻缺少Javadoc，文件头或特殊标记的任务设置。
绝大部分选项意义很明确. 特说明几个选项如下所示:
- 已生成的Javadoc
搜索和已生成Jautodoc注释完全匹配的Javadoc注释。 - 过期文件头
搜索和已生成Jautodoc文件头不匹配的文件头 - 搜索缺失标记
搜索缺失标记比如@author. 如果标记名后添加一个负号，则存在的标记不带有信息不会被提示或加上。但如果标记名后添加一个加号,则存在的标记不带有信息将会被提示。(如 @deprecated without a description).
