|
V1.0 李順利 2010年1月12日 目錄
發(fā)布Javadoc到Googel Code上... 8 關(guān)鍵詞
個(gè)性化地生成Javadoc文檔，svn eclipse 設(shè)置屬性 svn:keywords -TortoiseSVN,，李順利,， Javadoc 自定義標(biāo)記，javadoc tag,，javadoc version 自動(dòng)增加,，發(fā)布到google code Eclipse，javadoc,，語(yǔ)言,，編碼，自定義標(biāo)記,，亂碼,，版本，自動(dòng)增加,，sccs,，svn:keywords ，設(shè)置屬性,，模板,，google code, SCCS，VM options,， 前言
這一段時(shí)間在研究Javadoc的問(wèn)題,，前面發(fā)布的Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié)，總結(jié)了如何實(shí)現(xiàn)Javadoc到chm的轉(zhuǎn)換,，希望給大家?guī)?lái)了一些方便,，今天我們來(lái)說(shuō)說(shuō)如何利用Eclipse生成個(gè)性化的Javadoc 文檔，也希望大家支持,。 生成工具
Eclipse自帶的導(dǎo)出為Javadoc功能,，不使用cmd下的javadoc命令。 如何個(gè)性
會(huì)從語(yǔ)言,、編碼,、鏈接、自定義標(biāo)記,、設(shè)置版本的自動(dòng)增加（并引申Eclipse下如何設(shè)置SVN中的svn:keywords屬性）幾個(gè)方面來(lái)個(gè)性你的Javadoc文檔,。 個(gè)性分解
語(yǔ)言
如何設(shè)置生成的Javadoc默認(rèn)語(yǔ)言？ 解決方案在Eclipse導(dǎo)出Javadoc后面的配置VM options中加入-locale en_US,，但是此時(shí)注意的是,，如果把-locale en_US設(shè)置在后面的話，會(huì)報(bào)一個(gè)錯(cuò)誤,，大致是-locale en_US 在javadoc命令必須是在最前面,，默認(rèn)如果不寫-locale的話,，安裝locale語(yǔ)言來(lái)進(jìn)行設(shè)置，當(dāng)然我們中國(guó)人就是中文的了,。（當(dāng)然如果你工程默認(rèn)編碼是GBK而且您想生成中文的幫助文檔的話,，這寫都可以不要，使用默認(rèn)即可）,。 編碼
Java代碼編寫的使用有的使用GBK,，有的使用UTF-8，這個(gè)時(shí)候就會(huì)有區(qū)別,。使用GBK編碼的時(shí)候生成Javadoc文檔時(shí)沒(méi)有太大問(wèn)題的,，但是，要是整個(gè)項(xiàng)目的默認(rèn)編碼格式是UTF-8的話,，就會(huì)報(bào)警告：編碼 GBK 的不可映射字符,根本沒(méi)有成功生成Javadoc文檔,，如何解決？解決方案就是在生成Javadoc的時(shí)候?qū)?/span>VM options進(jìn)行編碼設(shè)置-encoding UTF-8 -charset UTF-8,。 （詳情請(qǐng)看Javadoc轉(zhuǎn)換chm幫助文檔的四種方法總結(jié)中預(yù)處理部分） 鏈接
如何使生成的Javadoc在注釋的時(shí)候有鏈接,？大家要知道，生成的Javadoc文檔默認(rèn)是html格式的,，當(dāng)然可以使用html標(biāo)記語(yǔ)言來(lái)寫一個(gè)鏈接,，實(shí)際上很簡(jiǎn)單，看我如何操作,。 @author <a href="http://www./lishunli/" target="_blank">ShunLi</a> 這樣就會(huì)生成如下效果
自定義標(biāo)記
在注釋的時(shí)候,，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) 一般我個(gè)人認(rèn)為都使用,，選擇a,，header就是在Javadoc中顯示的標(biāo)題。整個(gè)命令差不多就是這樣的：-tag created:a:"Created:" * 自定義標(biāo)記 @notes Created on 2010-1-12 這樣在生成Javadoc的時(shí)候就不會(huì)有報(bào)未定義的標(biāo)記的警告了,，但是在生成Javadoc的時(shí)候還是多了一句話： 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)記有可能會(huì)被Sun以后用的,，請(qǐng)?jiān)诙xname的時(shí)候盡量寫個(gè).號(hào)，不用管這句話了,。 生成的效果： 上面整個(gè)在VM Options你們?cè)O(shè)置的語(yǔ)句如下： -locale en_US -encoding UTF-8 -charset UTF-8 -tag notes:a:"Notes:"
設(shè)置版本的自動(dòng)增加
你在做項(xiàng)目的時(shí)候,，是不是想使用一個(gè)@version的標(biāo)記，但是我們也不能寫死了，不然每次都是@version V1.0什么的,，是不是想它能夠根據(jù)我們修改文件后能夠自動(dòng)增加或者賦值,。上網(wǎng)搜了很多，沒(méi)有一個(gè)能實(shí)用的,，后來(lái)還是在官網(wǎng)上找了一點(diǎn) @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 " 意思就是我們要使用SCCS（Source Code Control System）,，它會(huì)隨著SCCS的chedked out增長(zhǎng)變化，但是自己沒(méi)有深入地接觸SCCS,，查了一些資料就放棄走這條道了。后來(lái)想想自己使用了SVN,，看能不能借用SVN,。網(wǎng)上的資料很多，開(kāi)始繞了很多彎,，不知道搜索什么,，后來(lái)找到，就是設(shè)置一下SVN中的svn:keywords屬性,。 我一開(kāi)始在Eclipse中找到了設(shè)置屬性的地方,，但是有問(wèn)題，請(qǐng)看： 設(shè)置單個(gè)文件的屬性,，右鍵選擇項(xiàng)目,，下圖就有設(shè)置屬性
屬性名：輸入svn:keywords，輸入文本屬性為Id Revision Date Author（說(shuō)一下,，以前的LastChangedDate,、LastChangedBy、LastChangedRevision在SVN1.5里面不在使用,，SVN1.5以后使用Date,、Revision、Author,、HeadURL,、Id五個(gè)svn:keywords屬性，請(qǐng)參考SVN BOOK和SVN的版本自行修改書(shū)寫）,，下面有個(gè)紅色的警告：屬性不能應(yīng)用與文件夾（說(shuō)明svn:keywords僅能使用在文件上面）,，不過(guò)沒(méi)關(guān)系選擇遞歸，打上勾就可以了,。
這個(gè)對(duì)已經(jīng)提交到服務(wù)器上面的是沒(méi)有問(wèn)題,，但是新建的文件就沒(méi)有上面的屬性了，不建議大家使用這種方法,，這種方法僅適用于需要對(duì)單個(gè)文件設(shè)置屬性,。 下面就說(shuō)一下如何對(duì)所有的文件進(jìn)行配置，那當(dāng)然需要對(duì)SVN的配置文件進(jìn)行設(shè)置（不使用TortoiseSVN等服務(wù)器配置）。 如何的找到svn的config配置文件,？ 網(wǎng)上有高手介紹如下： 對(duì)于Windows xp用戶,，每個(gè)用戶的config文件一般都能在如下路徑中找到： C:\Documents and Settings\<Your_LoginName>\Application Data\Subversion\config
對(duì)于Windows vista /7 用戶，每個(gè)用戶的config文件一般都能在如下路徑中找到： C:\Documents and Settings\< Your_LoginName >\ AppData\Roaming\Subversion\config （注意：有可能你的AppData為隱藏的,，請(qǐng)去除隱藏后查找） 我的config配置文件路徑為："C:\Users\Administrator\AppData\Roaming\Subversion\config" %APPDATA% 是對(duì)應(yīng)你的"Application Data"目錄的環(huán)境變量,。將如下語(yǔ)句復(fù)制到任何Explorer窗口的地址欄中，最終將會(huì)直接打開(kāi)上述例子中的文件夾,，而無(wú)需在意Windows所使用的版本和語(yǔ)言,。 %APPDATA%\Subversion\config
如果你使用的是Windows，Eclipse和Subclipse Plugin以及JavaHL系結(jié)（可能還包括JavaSVN系結(jié),，不過(guò)我沒(méi)有進(jìn)行過(guò)親測(cè)）的話,，用此方法查找config文件也是可以的。 找到后用記事本打開(kāi),，在最后[auto-props]語(yǔ)句下面添加語(yǔ)句： *.java = svn:keywords=Id Revision Date Author *.xml = svn:keywords=Id Revision Date Author #默認(rèn)開(kāi)啟自動(dòng)屬性 [miscellany] enable-auto-props = yes # 結(jié)束 好了,，自動(dòng)屬性已經(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> 注意：使用自動(dòng)屬性的格式為$屬性名$,，其中屬性名請(qǐng)按照配置書(shū)寫，不要寫錯(cuò)也不要多空格,，不然SVN服務(wù)器解析不能 Commit到服務(wù)器上,，自動(dòng)修改后的結(jié)果如下： * <p> * <li>Test svn:keywords</li> * $Id: JavadocTest1.java 521 2010-01-12 08:30:18Z [email protected] $ * <br> * $Revision: 521 $: Revision of last commit * <br> * $Author: [email protected] $: 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)語(yǔ)言,。 生成模板
上面的操作也僅限對(duì)單個(gè)文件,，如果我們想保留我們的個(gè)性化，那當(dāng)然使用使用模板了 選擇Eclipse -> Preferences -> Java -> Code Style -> Code Templates -> Comments ->Types 后點(diǎn)擊Edit,，修改模板,，本人修改的模板如下： /** * * @author <a href="http://www./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上的意思就是能夠通過(guò)網(wǎng)址訪問(wèn)到Javadoc,，主要還是配置SVN的配置文件,， config文件也是可以的，在最后[auto-props]語(yǔ)句下面添加語(yǔ)句： # 發(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里有個(gè)link，輸入上面復(fù)制的網(wǎng)址,，到您Googel Code首頁(yè)就可以看到下面的鏈接
Links: 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自動(dòng)添加Id,Revision等keywords HOWTO: Publish Javadoc on Google Code 學(xué)習(xí)探討
如果有什么建議或意見(jiàn)可以通過(guò)Q：506817493 或 E：[email protected]，大家一起交流學(xué)習(xí),。 提供一些配置和參考文件的下載
順利寫于2010年1月12日 |
|
|
