如何個性化地生成Javadoc文檔

V1.0

李順利

2010年1月12日

關鍵詞

個性化地生成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.aygfsteel.com/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.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>

 */

注意：上面的環境是在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首頁就可以看到下面的鏈接

Links:

李順利博客

Javadoc

Blogs:

李順利博客

參考網站

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

Javadoc - The Java API Documentation Generator

使用Subversion進行版本控制（svnbook）

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

SVN使用詳解之如何設置svn:keywords

Gallery:使用Subversion

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

HOWTO: Publish Javadoc on Google Code

Subversion中的關鍵字替換

總結：Svn自動屬性設置

學習探討

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

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

順利寫于2010年1月12日