如何個性化地生成Javadoc文檔

V1.0

李順利

2010年1月12日

關(guān)鍵詞

個性化地生成Javadoc文檔，svn eclipse 設(shè)置屬性 svn:keywords -TortoiseSVN，李順利，

Javadoc 自定義標(biāo)記，javadoc tag，javadoc version 自動增加，發(fā)布到google code

Eclipse，javadoc，語言，編碼，自定義標(biāo)記，亂碼，版本，自動增加，sccs，svn:keywords ，設(shè)置屬性，模板，google code, SCCS，VM options，

前言

這一段時間在研究Javadoc的問題，前面發(fā)布的Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié)，總結(jié)了如何實現(xiàn)Javadoc到chm的轉(zhuǎn)換，希望給大家?guī)砹艘恍┓奖悖裉煳覀儊碚f說如何利用Eclipse生成個性化的Javadoc 文檔，也希望大家支持。

生成工具

Eclipse自帶的導(dǎo)出為Javadoc功能，不使用cmd下的javadoc命令。

如何個性

會從語言、編碼、鏈接、自定義標(biāo)記、設(shè)置版本的自動增加（并引申Eclipse下如何設(shè)置SVN中的svn:keywords屬性）幾個方面來個性你的Javadoc文檔。

個性分解

語言

如何設(shè)置生成的Javadoc默認(rèn)語言？

         解決方案在Eclipse導(dǎo)出Javadoc后面的配置VM options中加入-locale en_US，但是此時注意的是，如果把-locale en_US設(shè)置在后面的話，會報一個錯誤，大致是-locale en_US 在javadoc命令必須是在最前面，默認(rèn)如果不寫-locale的話，安裝locale語言來進(jìn)行設(shè)置，當(dāng)然我們中國人就是中文的了。（當(dāng)然如果你工程默認(rèn)編碼是GBK而且您想生成中文的幫助文檔的話，這寫都可以不要，使用默認(rèn)即可）。

編碼

Java代碼編寫的使用有的使用GBK，有的使用UTF-8，這個時候就會有區(qū)別。使用GBK編碼的時候生成Javadoc文檔時沒有太大問題的，但是，要是整個項目的默認(rèn)編碼格式是UTF-8的話，就會報警告：編碼 GBK 的不可映射字符,根本沒有成功生成Javadoc文檔，如何解決？解決方案就是在生成Javadoc的時候?qū)?/span>VM options進(jìn)行編碼設(shè)置-encoding UTF-8 -charset UTF-8。

（詳情請看Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié)中預(yù)處理部分）

鏈接

如何使生成的Javadoc在注釋的時候有鏈接？大家要知道，生成的Javadoc文檔默認(rèn)是html格式的，當(dāng)然可以使用html標(biāo)記語言來寫一個鏈接，實際上很簡單，看我如何操作。

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

這樣就會生成如下效果

自定義標(biāo)記

在注釋的時候，Eclipse中有默認(rèn)的標(biāo)記，像@author、@version等，都是以@打頭，現(xiàn)在我們要生成自己的標(biāo)記。

查看JDK中Javadoc命令的幫助文檔可以知道（進(jìn)入cmd敲javadoc –help）

知道需要使用-tag，其中name屬性就是你自定義標(biāo)記的名稱，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)

一般我個人認(rèn)為都使用，選擇a，header就是在Javadoc中顯示的標(biāo)題。整個命令差不多就是這樣的：-tag created:a:"Created:"

* 自定義標(biāo)記

@notes Created on 2010-1-12

這樣在生成Javadoc的時候就不會有報未定義的標(biāo)記的警告了，但是在生成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.

意思差不多就是你定義的自定義標(biāo)記有可能會被Sun以后用的，請在定義name的時候盡量寫個.號，不用管這句話了。

生成的效果：

上面整個在VM Options你們設(shè)置的語句如下：

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

設(shè)置版本的自動增加

         你在做項目的時候，是不是想使用一個@version的標(biāo)記，但是我們也不能寫死了，不然每次都是@version V1.0什么的，是不是想它能夠根據(jù)我們修改文件后能夠自動增加或者賦值。上網(wǎng)搜了很多，沒有一個能實用的，后來還是在官網(wǎng)上找了一點

@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。網(wǎng)上的資料很多，開始繞了很多彎，不知道搜索什么，后來找到，就是設(shè)置一下SVN中的svn:keywords屬性。

         我一開始在Eclipse中找到了設(shè)置屬性的地方，但是有問題，請看：

設(shè)置單個文件的屬性，右鍵選擇項目，下圖就有設(shè)置屬性

屬性名：輸入svn:keywords，輸入文本屬性為Id Revision Date Author（說一下，以前的LastChangedDate、LastChangedBy、LastChangedRevision在SVN1.5里面不在使用，SVN1.5以后使用Date、Revision、Author、HeadURL、Id五個svn:keywords屬性，請參考SVN BOOK和SVN的版本自行修改書寫），下面有個紅色的警告：屬性不能應(yīng)用與文件夾（說明svn:keywords僅能使用在文件上面），不過沒關(guān)系選擇遞歸，打上勾就可以了。

這個對已經(jīng)提交到服務(wù)器上面的是沒有問題，但是新建的文件就沒有上面的屬性了，不建議大家使用這種方法，這種方法僅適用于需要對單個文件設(shè)置屬性。

下面就說一下如何對所有的文件進(jìn)行配置，那當(dāng)然需要對SVN的配置文件進(jìn)行設(shè)置（不使用TortoiseSVN等服務(wù)器配置）。

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

網(wǎng)上有高手介紹如下：

對于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% 是對應(yīng)你的"Application Data"目錄的環(huán)境變量。將如下語句復(fù)制到任何Explorer窗口的地址欄中，最終將會直接打開上述例子中的文件夾，而無需在意Windows所使用的版本和語言。

%APPDATA%\Subversion\config

如果你使用的是Windows，Eclipse和Subclipse Plugin以及JavaHL系結(jié)（可能還包括JavaSVN系結(jié)，不過我沒有進(jìn)行過親測）的話，用此方法查找config文件也是可以的。

找到后用記事本打開，在最后[auto-props]語句下面添加語句：

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

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

#默認(rèn)開啟自動屬性

[miscellany]

enable-auto-props = yes

# 結(jié)束

好了，自動屬性已經(jīng)設(shè)置完畢，那么如何使用了？

* <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服務(wù)器解析不能

Commit到服務(wù)器上，自動修改后的結(jié)果如下：

* <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不想是中文的話，可以設(shè)置Eclipse的默認(rèn)語言。

生成模板

上面的操作也僅限對單個文件，如果我們想保留我們的個性化，那當(dāng)然使用使用模板了

選擇Eclipse -> Preferences -> Java -> Code Style -> Code Templates -> Comments ->Types 后點擊Edit，修改模板，本人修改的模板如下：

/**

 *

 * @author <a href="http://www.aygfsteel.com/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>

 */

注意：上面的環(huán)境是在Eclipse中已經(jīng)成功配置SVN后才能有效。

每次commit前后效果如下

發(fā)布Javadoc到Googel Code上

發(fā)布Javadoc到Googel Code上的意思就是能夠通過網(wǎng)址訪問到Javadoc，主要還是配置SVN的配置文件，

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

# 發(fā)布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

# 結(jié)束

生成Javadoc發(fā)布到Googel Code，找到剛發(fā)布Javadoc的index.html，復(fù)制鏈接

再到Googel Code 的Administrator里有個link，輸入上面復(fù)制的網(wǎng)址，到您Googel Code首頁就可以看到下面的鏈接

Links:

李順利博客

Javadoc

Blogs:

李順利博客

參考網(wǎng)站

How to Write Doc Comments for the Javadoc Tool（英文，適用于Java 5 和6）

Javadoc - The Java API Documentation Generator

使用Subversion進(jìn)行版本控制（svnbook）

Subversion(SVN)版本控制的操作技巧

SVN使用詳解之如何設(shè)置svn:keywords

Gallery:使用Subversion

如何讓subversion自動添加Id,Revision等keywords

HOWTO: Publish Javadoc on Google Code

Subversion中的關(guān)鍵字替換

總結(jié)：Svn自動屬性設(shè)置

學(xué)習(xí)探討

如果有什么建議或意見可以通過Q：506817493 或 E：leeshunli@qq.com，大家一起交流學(xué)習(xí)。

提供一些配置和參考文件的下載

順利寫于2010年1月12日