JBuilder2005創建開發文檔之標簽介紹

2019-11-18 12:00:52

字體：大中小

來源：轉載

供稿：網友

　　javadoc注釋由Javadoc標簽和描述性文本組成，你可以為類、接口添加注釋，也可為構造函數、值域、方法等類中的元素添加注釋。我們來看一個帶Javadoc注釋的程序，其代碼如下所示：
　　
　　代碼清單 1 Person.java
　　
　　1. package javadoc;
　　2. import java.io.Serializable;
　　3. /**
　　4. * <pre>描述人對象，擁有兩個屬性，分別是名字和性別。</pre>
　　5. * @see javadoc.tool.Car
　　6. * @version 1.0, 2005-04-12
　　7. * @author 陳雄華
　　8. * @since JDK1.3
　　9. */
　　10. public class Person implements Serializable
　　11. {
　　12. 　/**男性，值為{@value}*/
　　13. 　public static final int MALE = 1;
　　14. 　/**女性，值為{@value}*/
　　15. 　public static final int FEMALE = 2;
　　16. 　/**名字*/
　　17. 　PRotected String name;
　　18. 　/**年齡*/
　　19. 　protected int sex;
　　20. 　/**
　　21. 　* 構造一個Person實例。設定Person的名字和性別。
　　22. 　*
　　23. 　* @param name String 名字
　　24. 　* @param sex int 性別，有效值是{@link #MALE 男性}和{@link #FEMALE}
　　25. 　* @throws PersonArgumentException
　　26. 　* @see javadoc.tool.Car#drive(int)
　　27. 　*/
　　28. 　public Person(String name ,int sex) throws PersonArgumentException
　　29. 　{
　　30. 　　if(sex != MALE && sex != FEMALE)
　　31. 　　　throw new PersonArgumentException("參數不正確");
　　32. 　　　this.name = name;
　　33. 　　　this.sex = sex;
　　34. 　}
　　35. 　/**
　　36. 　* 獲取性別代號。
　　37. 　* @return int
　　38. 　* @see MALE
　　39. 　* @see FEMALE
　　40. 　*/
　　41. 　public int getSex()
　　42. 　{
　　43. 　　return sex;
　　44. 　}
　　45. 　/**
　　46. 　* 設置性別
　　47. 　* @param sex int
　　48. 　*/
　　49. 　public void setSex(int sex)
　　50. 　{
　　51. 　　this.sex = sex;
　　52. 　}
　　53. }
　　
　　所有的Javadoc注釋以/**開始，以*/結束，每個注釋包含一些描述性的文本及若干個Javadoc標簽。描述性的文本不但可以用平面文本，還可以使用Html文本；Javadoc標簽一般以"@"為前綴，有的也以"{@"為前綴，以"}"結束，如{@value }。
　　
　　第3~9行是類的注釋，它位于類定義代碼行前，其中第3行中的<pre></pre>標簽是HTML標簽，而第4~7行是Javadoc標簽，這段注釋映射在Javadoc文檔中的顯示樣式如下圖所示：
　　　 JBuilder2005創建開發文檔之標簽介紹（圖一）

　　圖 4 類注釋
　　
　　第12、14行是常量的注釋，位于常量定義代碼行之前，{@value}表示將常量的值輸出到Javadoc文檔中，第16、18是成員變量的注釋。成員常量和變量統稱為值域，它們在一起顯示：
　　　 JBuilder2005創建開發文檔之標簽介紹（圖二）

　　圖 5 成員常量/變量注釋摘要
　　
　　除注釋摘要以外，每個成員值域都有自己獨立的具體注釋。
　　
　　第20~27是類構造函數的注釋，構造函數有兩句描述信息，第一句是"構造一個Person實例。"第二句是"設定Person的名字和性別。"，在構造函數的摘要列表中僅會顯示第一句描述信息，用"。"分隔每句描述信息。而在構造函數的具體說明部分，則會顯示所有的描述信息。這個原則同樣適合于變量、方法的摘要，請看下面Javadoc幫助文檔中關于方法摘要及方法具體說明，如圖26-6，圖26-7所示：
　　　 JBuilder2005創建開發文檔之標簽介紹（圖三）

　　圖 6 方法摘要
　　　

　　圖 7 構造函數具體描述
　　
　　構造函數的Javadoc標簽比較多，@param為方法入參的說明，@throws為方法拋出異常的說明，<@link>標簽將在Javadoc文檔中提供一個鏈接到文檔中其它部分的URL。
　　
　　第35~40、45~48為方法的注釋，@return為方法返回類型的說明，前面我們已經提到Javadoc文檔包含了一個方法摘要列表，每個方法還對應一個具體描述部分，如getSex()的具體描述如下：
　　　 JBuilder2005創建開發文檔之標簽介紹（圖五）

　　圖 8 getSex()方法的具體說明
　　
　　通過這個實例的描述，我們對Javadoc的標簽和編寫有了大致的了解。注釋一般置于須注釋元素的前面，如類的注釋位于public class Xxx類聲明代碼的前面，而值域的注釋位于public int xxx前面。為了編寫美麗的Javadoc文檔，你不但需要把握簡單的HTML編寫知識，更需要了解Javadoc標簽的知識。
　　
　　不同版本的JDK所支持的Javadoc標簽是不一樣的，此外還可以按標簽適用的地方分成不同類型，如只適用于方法的@return標簽，我們稱之為方法標簽，只適用于變量的@serial標簽，我們稱之為值域標簽，以此類推。往往一個標簽適用于多種地方，下表對常用Javadoc標簽進行說明：
　　
　　表 2?1 javadoc標簽說明
　　 JBuilder2005創建開發文檔之標簽介紹（圖六）

　　此外還有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}幾個不常用的標簽，由于不常使用，我們展開敘述，感愛好的讀者可以通過http://www.java.sun.com/j2se/javadoc查看它們具體的幫助信息。
　　
　　下面我們對表中所列的幾個不輕易理解的Javadoc標簽舉例說明。
　　
　　* @see
　　
　　可以通過這個標簽在當前點鏈接到某個類、值域或方法的說明上。為了鏈接到當前類的值域或方法上，在值域和方法名前必須帶一個#號，如：
　　
　　@see #getSex()
　　@see #MALE
　　
　　也可以通過這個標簽鏈接到其它類的方法、值域的說明處，假設我們創建一個稱為javadoc的工程，在這個工程包括了代碼清單 1的javadoc.Person.java文件，現在我們在工程中再添加一個javadoc.tool.Car類，其程序代碼如下所示：
　　
　　1. package javadoc.tool;
　　2.
　　3. /**
　　4. * <pre>汽車對象類。</pre>
　　5. * @version 1.0, 2005-04-12
　　6. * @author 陳雄華
　　7. * @since JDK1.3
　　8. */
　　9. public class Car
　　10. {
　　11. 　public Car()
　　12. 　{
　　13. 　}
　　14. 　/**
　　15. 　* 按某一方向駕駛汽車
　　16. 　* @param direction int 方法
　　17. 　* @param speed int 速度
　　18. 　*/
　　19. 　public void drive(int direction,int speed)
　　20. 　{
　　21. 　　/*do sth*/
　　22. 　}
　　23. 　/**
　　24. 　* 朝前駕駛汽車
　　25. 　* @param speed int 速度
　　26. 　*/
　　27. 　public void drive(int speed)
　　28. 　{
　　29. 　　/*do sth*/
　　30. 　}
　　31. }
　　
　　假如Person類和Car類有關系，我們就希望在Person的Javadoc文檔中給出一個參見的Car文檔的鏈接，以便開發人員能夠順藤摸瓜找到有聯系的Car類的說明文檔。要達到這一目的可以在Person類的注釋中給出一個@see的標簽。
　　
　　1. /**
　　2. * <pre>描述人對象，擁有兩個屬性，分別是名字和性別。</pre>
　　3. * @see javadoc.tool.Car
　　4. * @version 1.0, 2005-04-12
　　5. * @author 陳雄華
　　6. * @since JDK1.3
　　7. */
　　
　　請看第3行的@see標簽，因為Car和Person類不在同一個包中，所以必須指定類的全名，當然，假如Person.java已經通過import chapter19.tool.Car;引入Car類，則@see可以直接用使用不帶包的類名：@see Car。所以Javadoc中的@see引用注釋和在Java代碼中引用類是相似的。
　　
　　一個更非凡的應用場合是從當前文檔中鏈接到重載方法，如Car中有兩個drive()的重載方法，如何通過@see鏈接到不同的重載方法和注釋中去呢？因為僅通過方法名無法定位，所以在方法名里面還需要指定入參的類型，請看下面的例子：
　　
　　·@see javadoc.tool.Car#drive(int,int)：鏈接到drive(int direction,int speed)。
　　
　　·@see javadoc.tool.Car#drive(int)：鏈接到drive(int speed)。
　　
　　假如注釋指定不正確，@see部分的注釋將不出現在Javadoc文檔中。
　　
　　* @link
　　
　　@link的@see很相似，唯一不同的是它可以嵌套在注釋的描述文本中，在生成Javadoc文檔時轉換成一個關聯鏈接。如Person的構造函數的注釋中的@link：
　　
　　1. /**
　　2. * 構造一個Person實例。設定Person的名字和性別。
　　3. *
　　4. * @param name String 名字
　　5. * @param sex int 性別，有效值是{@link #MALE }和{@link #FEMALE}
　　6. * @throws PersonArgumentException
　　7. * @see javadoc.tool.Car#drive(int)
　　8. */

上一篇：怎樣在Java實例開發的過程中使用進度條

下一篇：JBuilder2005創建開發文檔之編寫注釋