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

2024-07-21 02:15:16

字體：大中小

來源：轉載

供稿：網友

　　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文檔中的顯示樣式如下圖所示：

圖 4 類注釋

　　第12、14行是常量的注釋，位于常量定義代碼行之前，{@value}表示將常量的值輸出到javadoc文檔中，第16、18是成員變量的注釋。成員常量和變量統稱為值域，它們在一起顯示：

圖 5 成員常量/變量注釋摘要

　　除注釋摘要以外，每個成員值域都有自己獨立的詳細注釋。

　　第20~27是類構造函數的注釋，構造函數有兩句描述信息，第一句是"構造一個person實例。"第二句是"設定person的名字和性別。"，在構造函數的摘要列表中僅會顯示第一句描述信息，用"。"分隔每句描述信息。而在構造函數的詳細說明部分，則會顯示所有的描述信息。這個原則同樣適合于變量、方法的摘要，請看下面javadoc幫助文檔中關于方法摘要及方法詳細說明，如圖26-6，圖26-7所示：

圖 6 方法摘要

圖 7 構造函數詳細描述

　　構造函數的javadoc標簽比較多，@param為方法入參的說明，@throws為方法拋出異常的說明，<@link>標簽將在javadoc文檔中提供一個鏈接到文檔中其它部分的url。

　　第35~40、45~48為方法的注釋，@return為方法返回類型的說明，前面我們已經提到javadoc文檔包含了一個方法摘要列表，每個方法還對應一個詳細描述部分，如getsex()的詳細描述如下：

圖 8 getsex()方法的詳細說明

　　通過這個實例的描述，我們對javadoc的標簽和編寫有了大致的了解。注釋一般置于須注釋元素的前面，如類的注釋位于public class xxx類聲明代碼的前面，而值域的注釋位于public int xxx前面。為了編寫優美的javadoc文檔，你不但需要掌握簡單的html編寫知識，更需要了解javadoc標簽的知識。

　　不同版本的jdk所支持的javadoc標簽是不一樣的，此外還可以按標簽適用的地方分成不同類型，如只適用于方法的@return標簽，我們稱之為方法標簽，只適用于變量的@serial標簽，我們稱之為值域標簽，以此類推。往往一個標簽適用于多種地方，下表對常用javadoc標簽進行說明：

　　表 2?1 javadoc標簽說明

標簽	說明	jdk 1.1 doclet	標準doclet	標簽類型
@author 作者	作者標識	√	√	包、類、接口
@version 版本號	版本號	√	√	包、類、接口
@param 參數名描述	方法的入參名及描述信息，如入參有特別要求，可在此注釋。	√	√	構造函數、方法
@return 描述	對函數返回值的注釋	√	√	方法
@deprecated 過期文本	標識隨著程序版本的提升，當前api已經過期，僅為了保證兼容性依然存在，以此告之開發者不應再用這個api。	√	√	包、類、接口、值域、構造函數、方法
@throws異常類名	構造函數或方法所會拋出的異常。		√	構造函數、方法
@exception 異常類名	同@throws。	√	√	構造函數、方法
@see 引用	查看相關內容，如類、方法、變量等。	√	√	包、類、接口、值域、構造函數、方法
@since 描述文本	api在什么程序的什么版本后開發支持。	√	√	包、類、接口、值域、構造函數、方法
{@link包.類#成員標簽}	鏈接到某個特定的成員對應的文檔中。		√	包、類、接口、值域、構造函數、方法
{@value}	當對常量進行注釋時，如果想將其值包含在文檔中，則通過該標簽來引用常量的值。		√(jdk1.4)	靜態值域

　　此外還有@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. */

　　帶{}的javadoc標簽象一個變量，在轉換成文檔后，將替換成一個具體的值或鏈接。

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

下一篇：Eclipse Form程序設計指南之入門