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首頁就能夠看到下面的連接