如何規範生成JAVADOC幫助文檔

如何規範生成JAVADOC幫助文檔

1.文本註釋（/** */）也叫歸檔註釋。

       歸檔註釋是一種專用註釋；當它放在類或類成員聲明以前時，javadoc工具能夠提取出這些註釋並用它們來生成程序的HTML文檔。歸檔註釋一般入在類、接口、方法及字段定義以前。

 

2.文本註釋中的「文檔標記」（Doctags）是一些以「@」開頭的命令;

 

3.javadoc只能爲public（公共）和protected（受保護）成員處理註釋文檔。「private」（私有）和「友好」成員（即沒有訪問控制符）的註釋會被忽略，咱們看不到任何輸出（也能夠用-private標記包括private成員）。

 

4.類文檔標記

類文檔能夠包括用於版本信息以及做者姓名的標記。

（1）@version

格式以下：

@version 版本信息

其中，「版本信息」表明任何適合做爲版本說明的資料。若在javadoc命令行使用了「-version」標記，就會從生成的HTML文檔裏提取出版本信息。

（2） @author

格式以下：

@author 做者信息

其中，「做者信息」包括您的姓名、電子函件地址或者其餘任何適宜的資料。若在javadoc命令行使用了「-author」標記，就會專門從生成的HTML文檔裏提取出做者信息。

可爲一系列做者使用多個這樣的標記，但它們必須連續放置。所有做者信息會一塊兒存入最終HTML代碼的單獨一個段落裏。

 

5.方法文檔標記

方法容許使用針對參數、返回值以及異常的文檔標記。

（1）@param

格式以下：

@param 參數名 說明

其中，「參數名」是指參數列表內的標識符，而「說明」表明一些可延續到後續行內的說明文字。一旦遇到一個新文檔標記，就認爲前一個說明結束。可以使用任意數量的說明，每一個參數一個。

（2）@return

格式以下：

@return 說明

其中，「說明」是指返回值的含義。它可延續到後面的行內。

（3）@exception

有關「異常」（Exception）的詳細狀況，

        @exception 完整類名 說明

        「完整類名」明確指定了一個違例類的名字，它是在其餘某個地方定義好的。

       而「說明」（一樣能夠延續到下面的行）告訴咱們爲何這種特殊類型的違例會在方法調用中出現。

（4）@deprecated該標記的做用是建議用戶沒必要再使用一種特定的功能，由於將來改版時可能摒棄。

        若將一個方法標記爲@deprecated，則使用該方法時會收到編譯器的警告。

 

順便提一下在eclipse下，當鼠標處於類，方法定義行時，按Alt+Shift+J，就能夠快速添加文檔註釋。至於如何導出javadoc文檔，eclipse環境下，file> export > javadoc >這裏只要選中你要導出的*.java文件便可，要十分注意的是，一般不少人的classpath環境下，帶有 %classpath%這使javadoc命令沒法正確地執行。而提示的出錯信息一般是IlleagalArgumentException。