javadoc 生成自定义的标签

转自：http://www.blogjava.net/lishunli/archive/2010/01/12/309218.html

Technorati 标记: tools

关键词

个性化地生成Javadoc文档，svn eclipse 设置属性 svn:keywords -TortoiseSVN，李顺利，

Javadoc 自定义标记，javadoc tag，javadoc version 自动增加，发布到google code

Eclipse，javadoc，语言，编码，自定义标记，乱码，版本，自动增加，sccs，svn:keywords ，设置属性，模板，google code, SCCS，VM options，

前言

这一段时间在研究Javadoc的问题，前面发布的Javadoc转换chm帮助文档的四种方法总结，总结了如何实现Javadoc到chm的转换，希望给大家带来了一些方便，今天我们来说说如何利用Eclipse生成个性化的Javadoc 文档，也希望大家支持。

生成工具

Eclipse自带的导出为Javadoc功能，不使用cmd下的javadoc命令。

如何个性

会从语言、编码、链接、自定义标记、设置版本的自动增加（并引申Eclipse下如何设置SVN中的svn:keywords属性）几个方面来个性你的Javadoc文档。

解决方案在Eclipse导出Javadoc后面的配置VM options中加入-locale en_US，但是此时注意的是，如果把-locale en_US设置在后面的话，会报一个错误，大致是-locale en_US 在javadoc命令必须是在最前面，默认如果不写-locale的话，安装locale语言来进行设置，当然我们中国人就是中文的了。（当然如果你工程默认编码是GBK而且您想生成中文的帮助文档的话，这写都可以不要，使用默认即可）。

编码

Java代码编写的使用有的使用GBK，有的使用UTF-8，这个时候就会有区别。使用GBK编码的时候生成Javadoc文档时没有太大问题的，但是，要是整个项目的默认编码格式是UTF-8的话，就会报警告：编码 GBK 的不可映射字符,根本没有成功生成Javadoc文档，如何解决？解决方案就是在生成Javadoc的时候对VM options进行编码设置-encoding UTF-8 -charset UTF-8。

（详情请看Javadoc转换chm帮助文档的四种方法总结中预处理部分）

链接

如何使生成的Javadoc在注释的时候有链接？大家要知道，生成的Javadoc文档默认是html格式的，当然可以使用html标记语言来写一个链接，实际上很简单，看我如何操作。

@author <a href="http://www.blogjava.net/lishunli/" target="_blank">ShunLi</a>

这样就会生成如下效果

自定义标记

在注释的时候，Eclipse中有默认的标记，像@author、@version等，都是以@打头，现在我们要生成自己的标记。

查看JDK中Javadoc命令的帮助文档可以知道（进入cmd敲javadoc –help）

知道需要使用-tag，其中name属性就是你自定义标记的名称，locations官方上有以下解释

Placement of tags - The Xaoptcmf part of the argument determines where in the source code the tag is allowed to be placed, and whether the tag can be disabled (using X). You can supply either a, to allow the tag in all places, or any combination of the other letters:

X (disable tag)
a (all)
o (overview)
p (packages)
t (types, that is classes and interfaces)
c (constructors)
m (methods)
f (fields)

一般我个人认为都使用，选择a，header就是在Javadoc中显示的标题。整个命令差不多就是这样的：-tag created:a:"Created:"

* 自定义标记

@notes Created on 2010-1-12

这样在生成Javadoc的时候就不会有报未定义的标记的警告了，但是在生成Javadoc的时候还是多了一句话：

Note: Custom tags that could override future standard tags: @notes. To avoid potential overrides, use at least one period character (.) in custom tag names.

意思差不多就是你定义的自定义标记有可能会被Sun以后用的，请在定义name的时候尽量写个.号，不用管这句话了。

生成的效果：

上面整个在VM Options你们设置的语句如下：

-locale en_US -encoding UTF-8 -charset UTF-8 -tag notes:a:"Notes:"

设置版本的自动增加

你在做项目的时候，是不是想使用一个@version的标记，但是我们也不能写死了，不然每次都是@version V1.0什么的，是不是想它能够根据我们修改文件后能够自动增加或者赋值。上网搜了很多，没有一个能实用的，后来还是在官网上找了一点

@version (reference page)

The Java Software convention for the argument to the @version tag is the SCCS string "%I%, %G%", which converts to something like "1.39, 02/28/97" (mm/dd/yy) when the file is checked out of SCCS.

意思就是我们要使用SCCS（Source Code Control System），它会随着SCCS的chedked out增长变化，但是自己没有深入地接触SCCS，查了一些资料就放弃走这条道了。后来想想自己使用了SVN，看能不能借用SVN。网上的资料很多，开始绕了很多弯，不知道搜索什么，后来找到，就是设置一下SVN中的svn:keywords属性。

我一开始在Eclipse中找到了设置属性的地方，但是有问题，请看：

设置单个文件的属性，右键选择项目，下图就有设置属性

属性名：输入svn:keywords，输入文本属性为Id Revision Date Author（说一下，以前的LastChangedDate、LastChangedBy、LastChangedRevision在SVN1.5里面不在使用，SVN1.5以后使用Date、Revision、Author、HeadURL、Id五个svn:keywords属性，请参考SVN BOOK和SVN的版本自行修改书写），下面有个红色的警告：属性不能应用与文件夹（说明svn:keywords仅能使用在文件上面），不过没关系选择递归，打上勾就可以了。

这个对已经提交到服务器上面的是没有问题，但是新建的文件就没有上面的属性了，不建议大家使用这种方法，这种方法仅适用于需要对单个文件设置属性。

下面就说一下如何对所有的文件进行配置，那当然需要对SVN的配置文件进行设置（不使用TortoiseSVN等服务器配置）。

如何的找到svn的config配置文件？

网上有高手介绍如下：

对于Windows xp用户，每个用户的config文件一般都能在如下路径中找到：

C:\Documents and Settings\<Your_LoginName>\Application Data\Subversion\config

对于Windows vista /7 用户，每个用户的config文件一般都能在如下路径中找到：

C:\Documents and Settings\< Your_LoginName >\ AppData\Roaming\Subversion\config

（注意：有可能你的AppData为隐藏的，请去除隐藏后查找）

我的config配置文件路径为："C:\Users\Administrator\AppData\Roaming\Subversion\config"

%APPDATA% 是对应你的"Application Data"目录的环境变量。将如下语句复制到任何Explorer窗口的地址栏中，最终将会直接打开上述例子中的文件夹，而无需在意Windows所使用的版本和语言。

%APPDATA%\Subversion\config

如果你使用的是Windows，Eclipse和Subclipse Plugin以及JavaHL系结（可能还包括JavaSVN系结，不过我没有进行过亲测）的话，用此方法查找config文件也是可以的。

找到后用记事本打开，在最后[auto-props]语句下面添加语句：

*.java = svn:keywords=Id Revision Date Author

*.xml = svn:keywords=Id Revision Date Author

#默认开启自动属性

[miscellany]

enable-auto-props = yes

# 结束

好了，自动属性已经设置完毕，那么如何使用了？

*

* <li>Test svn:keywords</li>

* $Id$

*

* $Revision$: Revision of last commit

*

* $Author$: Author of last commit

*

* $Date$:Date of last commit

*

注意：使用自动属性的格式为$属性名$，其中属性名请按照配置书写，不要写错也不要多空格，不然SVN服务器解析不能

Commit到服务器上，自动修改后的结果如下：

*

* <li>Test svn:keywords</li>

* $Id: JavadocTest1.java 521 2010-01-12 08:30:18Z XXX@gmail.com $

*

* $Revision: 521 $: Revision of last commit

*

* $Author: XXX@gmail.com $: Author of last commit

*

* $Date: 2010-01-12 16:30:18 +0800 (周二, 12 一月 2010) $:Date of last commit

*

上面的Date不想是中文的话，可以设置Eclipse的默认语言。

生成模板

上面的操作也仅限对单个文件，如果我们想保留我们的个性化，那当然使用使用模板了

选择Eclipse -> Preferences -> Java -> Code Style -> Code Templates -> Comments ->Types 后点击Edit，修改模板，本人修改的模板如下：

/**

* @author <a href="http://www.blogjava.net/lishunli/" target="_blank">${user}</a>

* @notes Created on ${date}

* Revision of last commit:$$Revision$$

* Author of last commit:$$Author$$

* Date of last commit:$$Date$$

*

注意：上面的环境是在Eclipse中已经成功配置SVN后才能有效。

每次commit前后效果如下

发布Javadoc到Googel Code上

发布Javadoc到Googel Code上的意思就是能够通过网址访问到Javadoc，主要还是配置SVN的配置文件，

config文件也是可以的，在最后[auto-props]语句下面添加语句：

# 发布Javadoc到Google Code上

*.txt = svn:mime-type=text/plain

*.html = svn:mime-type=text/html

*.css = svn:mime-type=text/css

*.png = svn:mime-type=image/png

*.jpg = svn:mime-type=image/jpeg

# 结束

生成Javadoc发布到Googel Code，找到刚发布Javadoc的index.html，复制链接

再到Googel Code 的Administrator里有个link，输入上面复制的网址，到您Googel Code首页就可以看到下面的链接