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文档。

个性分解

语言

如何设置生成的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

# 结束

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

* <p>

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

* $Id$

* <br>

* $Revision$: Revision of last commit

* <br>

* $Author$: Author of last commit

* <br>

* $Date$:Date of last commit

* <br>

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

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

* <p>

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

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

* <br>

* $Revision: 521 $: Revision of last commit

* <br>

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

* <br>

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

* <br>

上面的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}<br>

* Revision of last commit:$$Revision$$<br>

* Author of last commit:$$Author$$<br>

* Date of last commit:$$Date$$<br>

* <p>

*/

注意：上面的环境是在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首页就能够看到下面的连接