JAutodoc指南

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).