javadoc如何生成API文檔

如何規範生成JAVADOC幫助文檔

       javadoc使程式與文檔密切結合起來，作為規範的開發步驟，程式的文檔是可維護，可擴充的基礎。當程式修改後，文檔能相應改變，使文檔與程式的一緻性非常好，JAVA程式設計要養成規範的程式注釋。

       java的注釋分成三種：單行注釋（//）、多行注釋（）、文本注釋（）也叫歸檔注釋。歸檔注釋是一種專用注釋；當它放在類或類成員聲明之前時，javadoc工具可以提取出這些注釋并用它們來生成程式的HTML文檔。歸檔注釋通常入在類、接口、方法及字段定義之前。歸檔注釋中可以使用幾組特殊标記以提供更為特定的資訊，這種注釋從結束。在JAVA代碼開發過程中，形成規範文檔是很重要的，要充分利用SUN公司提供的javadoc.exe這個指令。

       文本注釋中的“文檔标記”（Doc tags）是一些以“@”開頭的指令，置于注釋行的起始處（但前導的*會被忽略）。一個類和接口注釋正好位于一個類和接口定義之前；而一個方法注釋正好位于一個方法定義的前面。變量注釋正好位于變量定義之前。注意javadoc隻能為public（公共）和protected（受保護）成員處理注釋文檔。“private”（私有）和“友好”成員（即沒有通路控制符）的注釋會被忽略，我們看不到任何輸出（也可以用-private标記包括private成員）。這樣做是有道理的，因為隻有public和protected成員才可在檔案之外使用，這是客戶程式員的希望。然而，所有類注釋都會包含到輸出結果裡。 下面重點介紹類和方法的文檔标記。javadoc @相當于關鍵字作用，标注參數，不能寫錯。<br>表示換行。

類文檔标記 

類文檔可以包括用于版本資訊以及作者姓名的标記。

（ 

格式如下： 

@version 版本資訊 

其中，“版本資訊”代表任何适合作為版本說明的資料。若在javadoc指令行使用了“-version”标記，就會從生成的HTML文檔裡提取出版本資訊。

（2） @author 

格式如下： 

@author 作者資訊 

其中，“作者資訊”包括您的姓名、電子函件位址或者其他任何适宜的資料。若在javadoc指令行使用了“-author”标記，就會專門從生成的HTML文檔裡提取出作者資訊。 

可為一系列作者使用多個這樣的标記，但它們必須連續放置。全部作者資訊會一起存入最終HTML代碼的單獨一個段落裡。

方法文檔标記 

方法允許使用針對參數、傳回值以及異常的文檔标記。

（ 

格式如下： 

@param 參數名 說明 

其中，“參數名”是指參數清單内的辨別符，而“說明”代表一些可延續到後續行内的說明文字。一旦遇到一個新文檔标記，就認為前一個說明結束。可使用任意數量的說明，每個參數一個。

（ 

格式如下： 

@return 說明 

其中，“說明”是指傳回值的含義。它可延續到後面的行内。

（ 

有關“違例”（Exception）的詳細情況，我們會在第9章講述。簡言之，它們是一些特殊的對象，若某個方法失敗，就可将它們“扔出”對象。調用一個方法時，盡管隻有一個違例對象出現，但一些特殊的方法也許能産生任意數量的、不同類型的違例。所有這些違例都需要說明。是以，違例标記的格式如下： 

@exception 完整類名 說明 

其中，“完整類名”明确指定了一個違例類的名字，它是在其他某個地方定義好的。而“說明”（同樣可以延續到下面的行）告訴我們為什麼這種特殊類型的違例會在方法調用中出現。

（4） @deprecated 

這是Java 1.1的新特性。該标記用于指出一些舊功能已由改進過的新功能取代。該标記的作用是建議使用者不必再使用一種特定的功能，因為未來改版時可能摒棄這一功能。若将一個方法标記為@deprecated，則使用該方法時會收到編譯器的警告。

       順便提一下在eclipse下，當滑鼠處于類，方法定義行時，按Alt+Shift+J，就可以快速添加文檔注釋。至于如何導出javadoc文檔，eclipse環境下，file > export > javadoc > 這裡隻要選中你要導出的*.java檔案即可，要十分注意的是，通常很多人的classpath環境下，帶有 %classpath% 這使javadoc指令無法正确地執行。而提示的出錯資訊通常是IlleagalArgumentException。