JavaDoc命令使用說明

時間 2019-11-09

原文原文鏈接

javadoc的命令行語法以下：
    javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

參數能夠按照任意順序排列。下面分別就這些參數和相關的一些內容進行說明：
    Packagenames 包列表。這個選項能夠是一系列的包名（用空格隔開），例如java.lang java.lang.reflect java.awt。不過，由於javadoc不遞歸做用於子包，不容許對包名使用通配符；因此你必須顯示地列出但願創建文檔的每個包。

    Sourcefiles 源文件列表。這個選項能夠是一系列的源文件名（用空格隔開），可使用通配符。javadoc容許四種源文件：類源代碼文件、包描述文件、整體概述文件、其餘雜文件。

◇ 類源代碼文件：類或者接口的源代碼文件。

◇ 包描述文件：每個包均可以有本身的包描述文件。包描述文件的名稱必須是"package.html"，與包的.java文件放置在一塊兒。包描述文件的內容一般是使用HTML標記寫的文檔。javadoc執行時將自動尋找包描述文件。若是找到，javadoc將首先對描述文件中<body> </body>之間的內容進行處理，而後把處理結果放到該包的Package Summary頁面中，最後把包描述文件的第一句（緊靠<body>）放到輸出的Overview summary頁面中，並在語句前面加上該包的包名。

◇ 整體概述文件：javadoc能夠建立一個整體概述文件描述整個應用或者全部包。整體概述文件能夠被任意命名，也能夠放置到任意位置。-overview 選項能夠指示整體概述文件的路徑和名稱。整體概述文件的內容是使用HTML標記寫的文檔。javadoc在執行的時候，若是發現-overview選項，那麼它將首先對文件中<body></body>之間的內容進行處理；而後把處理後的結果放到輸出的Overview summary 頁面的底部；最後把整體概述文件中的第一句放到輸出的Overview summary頁面的頂部。

◇ 其餘雜文件：這些文件一般是指與javadoc輸出的HTML文件相關的一些圖片文件、Java源代碼文件（.java）、Java程序（.class）、Java小程序（Applets）、HTML文件。這些文件必須放在doc-files目錄中。每個包均可以有本身的doc- files目錄。舉個例子，你但願在java.awt.Button的HTML文檔中使用一幅按鈕的圖片（Button.gif）。首先，你必須把圖片文件放到C:usersrcjavaawtdoc-files中；而後在Button.java文件中加入下面註釋
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
    @files 包含文件。爲了簡化javadoc命令，你能夠把須要創建文檔的文件名和包名放在一個或多個文本文件中。例如，爲了簡化下面命令：
javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3

你能夠創建一個名稱爲mypackage.txt的文件，其內容以下：
com.mypackage1
com.mypackage2
com.mypackage3
而後執行下面命令便可：
javadoc -d apidoc @mypackage.txt

    options 命令行選項。javadoc使用doclets（doclets是指用doclet API編寫的程序。）來肯定輸出的內容和格式。命令行選項中一部分是可用於全部doclet的通用選項，一部分是由默認的標準doclet提供的專用的選項。下面對各自一些經常使用的選項分別進行介紹：

通用選項：
◇ -1.1 生成具備javadoc 1.1版本生成的文檔的外觀和功能的文檔。不是全部的選項均可以用於-1.1選項，具體可使用javadoc -1.1 -help察看。

◇ -help 顯示聯機幫助。

◇ -bootclasspath classpathlist 指定"根類"（一般是Java平臺自帶的一些類。例如java.awt.*等）的路徑。

◇ -sourcepath sourcepathlist 指定包的源文件搜索路徑。可是必須注意，只有在javadoc命令中指定了包名的時候纔可使用-sourcepath選項。若是指定了包名，而省略了- sourcepath，那麼javadoc使用類路徑查找源文件。舉例說明：假定你打算爲com.mypackage創建文檔，其源文件的位置是C: usersrc。那麼你可使用下面的命令：
javadoc -sourcepath c:usersrc com.mypackage

◇ -classpath classpathlist 指定javadoc查找"引用類"的路徑。引用類是指帶文檔的類加上它們引用的任何類。javadoc將搜索指定路徑的全部子目錄。 Classpathlist能夠包含多個路徑（使用;隔開）。若是省略-classpath，則javadoc使用-sourcepath查找源文件和類文件。舉例說明：假定你打算爲com.mypackage創建文檔，其源文件的位置是C:usersrc，包依賴C:userlib中的庫。那麼你可使用下面的命令：
javadoc -classpath c:userlib -sourcepath c:usersrc com.mypackage

◇ -overview pathfilename 告訴javadoc從pathfilename所指定的文件中獲取概述文檔，而且把它放到輸出的概述頁面（overview-summary.html）中。其中pathfilename是相對於-sourcepath的相對路徑。

◇ -public 只顯示公共類以及成員。

◇ -protected 只顯示受保護的和公共的類以及成員。缺省選項。

◇ -package只顯示包、受保護的和公共的類以及成員。

◇ -private 顯示全部類和成員。

◇ -doclet class 指定javadoc產生輸出內容的自定義doclet類。若是忽略這個選項，javadoc將使用默認的doclet產生一系列HTML文檔。

◇ -docletpath classpathlist 與- doclet選項相關，制定自定義的doclet類文件的路徑。Classpathlist能夠包含多條路徑（用;隔開）。

◇ -verbose 在javadoc運行時提供更詳細的信息。
標準doclet專用選項：

◇ -author 在生成的文檔中包含"做者"項。

◇ - d directory 指定javadoc保存生成的HTML文件的目錄。省略該選項將把文件保存在當前目錄。Directory能夠是絕對目錄，也能夠是相對當前目錄的相對目錄。

◇ -version 在生成的文檔中包含"版本"項。

◇ -use 爲類和包生成"use"（用法）頁面。這些頁面描述了該類和包在javadoc命令涉及的文件中被使用的狀況。例如：對於給定的類C，在C的用法頁面中將包含C的子類，類型爲C的域，返回變量類型爲C的方法以及在參數中有變量類型爲C的方法和構造器。

◇ -splitindex 把索引文件按照字母順序分爲多個文件。每個文件對應一個字母。

◇ -windowtitle title 指定輸出的HTML文檔的標題。

◇ -header header 指定輸出的HTML文檔的頁眉文本。

◇ -footer footer 指定輸出的HTML文檔的腳註文本。

◇ -bottom text 指定輸出的HTML文檔底部的文本。

◇ - group groupheading packagepatten;packagepatten;… 在整體概述頁面中按照命令的指定方式分隔各個包。例如執行下面命令：
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
在頁面中將有以下結果：
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new

◇ - noindex 不輸出索引文件。

◇ - help 在文件的導航條中忽略help連接。

◇ - helpfile pathfilename 指定導航條中的help連接所指向的幫助文件。忽略該選項，javadoc將生成缺省的幫助文件。

◇ -stylesheetfile pathfilename 指定javadoc的HTML樣式表文件的路徑。忽略該選項，javadoc將自動產生一個樣式表文件stylesheet.css。

    JavaDoc文檔標記
    javadoc註釋以"/**"開始，以"*/"結束，裏面能夠包含普通文本、HTML標記和javadoc標記。javadoc只處理源文件中在類/接口定義、方法、域、構造器以前的註釋，忽略位於其餘地方的註釋。舉例以下：
/**
*Demo--<b>Helloworld</b>
*@author sunjl
*@version 1.0 2001/10/15
*/
public class myHelloworld
{
    /**
    *在main( )方法中使用的顯示用字符串
    *@see #main(java.lang.String[])
    */
    static String SDisplay;
    /**
    *顯示HelloWorld
    *@param args 從命令行中帶入的字符串
    *@return 無
    */
    public static void main(String args[]){
        SDisplay = "Hello World " ;
        System.out.println( SDisplay );
    }
}

使用下面命令：

javadoc -private -d doc -author -version myHelloworld.java

便可以生成漂亮的關於myHelloworld.java的API文檔了。

上面例子中以@開頭的標記就是javadoc標記。在Java程序中正確使用javadoc標記是一個良好的註釋習慣，將很是有助於javadoc自動從源代碼文件生成完整的格式化API文檔。下面就對各類標記進行詳細說明。

◇ @author name-text 指定生成文檔中的"做者"項，從JDK/SDK 1.0開始引入。name-text能夠指定多個名字（使用","隔開）。文檔註釋能夠包含多個類。

◇ {@docroot} 表明產生文檔的根路徑，從JDK/SDK 1.3開始引入。用法舉例以下
/**
*see the <a href={@docroot}/copyright.html>copyright</a>
*/
假定生成文檔的根目錄是doc，上面註釋所在的文件最後生成的文件是docutilityutl.html，那麼"copyright"的連接會指向..copyright.html。

◇ @deprecated deprecated-text 添加註釋，代表不推薦使用該API。

◇ @exception class-name description @throw的同義標記，從JDK/SDK 1.0開始引入。

◇ {@link package.class#member label} 插入指向package.class#member的內嵌連接，從JDK/SDK 1.2開始引入。舉例說明，假定註釋中有以下文檔：
/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */
那麼javadoc最終生成的HTML頁面中將有以下內容
Use the <a href = "Component.html#getComponentAt(int,int)" > getComponentAt </a> method.

◇ @param parameter-name description 描述參數，從JDK/SDK 1.0開始引入。

◇ @return description 描述返回值，從JDK/SDK 1.0開始引入。

◇ @see reference 添加"參見"標題，其中有指向reference的連接或者文本項，從JDK/SDK 1.0開始引入。@see標記有三種形式，下面分別說明：
（1）、@see "string" 爲"string"添加文本項，不產生連接。
（2）、@see <a href="URL#Value">Label</a> 使用HTML標記產生連接
（3）、@see package.class#member Label 使用Java語言的名字package.class #member產生連接。

◇ @serial field-description 用於缺省可序列化域的註釋，從JDK/SDK 1.2開始引入。

◇ @serialField field-name field-type field-description 創建Serializable類的serialPersistentFields成員的ObjectStreamField組件的文檔，從JDK/SDK 1.2開始引入。

◇ @serialData data-description data-description創建數據序列和類型的文檔，從JDK/SDK 1.2開始引入。

◇ @since since-text 利用since-text內容爲文檔增長"since"標題，從JDK/SDK 1.1開始引入。

◇ @throws class-name description 與@exception同義。用class-name和description爲輸出文檔添加"拋出"標題，從JDK/SDK 1.2開始引入。

◇ @version version-text 添加"版權"標題，從JDK/SDK 1.0開始引入。
    上面介紹了標準doclet提供的全部標記。不過，須要注意這些標記的使用是有位置限制的。其中能夠出如今類或者接口文檔註釋中的標記有：@see、 {@link}、@since、@deprecated、@author、@version。能夠出如今方法或者構造器文檔註釋中的標記有：@see、 {@link}、@since、@deprecated、@param、@return、@throws、@exception、 @serialData。能夠出如今域文檔註釋中的有：@see、{@link}、@since、@desprecated、@serial、 @serialField。

    除了javadoc自身提供的標準標記之外，咱們能夠定製本身的標記嗎？固然能夠。只須要對javadoc標準的 doclet程序進行擴充便可。實際上，利用javadoc提供的doclet API，不只能夠擴充doclet標記，甚至還能夠改變javadoc的整個輸出。爲了知足須要，你可使javadoc輸出普通文本、XML文件等。由於擴充doclet涉及到Java編程，本文再也不作深刻介紹。

    總之，javadoc提供了完整規範的API文檔功能。在軟件項目管理中，合理地使用javadoc不只能夠減小開發時的文檔工做量，提升效率；並且還很是有利於未來軟件的修改和維護。

JavaDoc 書寫規範：
一、 File Header Comments : 每一個文件都應該加上文件頭標記，包括文件名、修改歷史、版權信息和附加信息。例如：

/**
* @(#)demo.java 1.00 2002/05/27
*
* Copyright (c) 2000-2002 中國平安保險股份有限公司版權全部
* Ping An Insurance Company of China. All rights reserved.

* This software is the confidential and proprietary
* information of Ping An Insurance Company of China.
* ("Confidential Information"). You shall not disclose
* such Confidential Information and shall use it only
* in accordance with the terms of the contract agreement
* you entered into with Ping An.
*/

二、class description:類信息，歸納的描述類的功能和實現。
/** class description
*/

三、Variable Description:描述變量的意義和取值含義。
/** var variable description
*/

四、Method Description:標明每一個方法的輸入、輸出參數和返回值類型，說明特殊變量取值的含義。相關類文檔連接。
/** method description
* @param var signification
* @exception exception class name
* @return return_value return signification
*/

五、Association Description:關聯類文檔描述，在註釋當中須要參引其它文檔描述的地方，可在相應的註釋當中以下插入：
/** method description
* @param var signification
* @exception exception class name
* @return return_value return signification
* @see package.class#member label
*/

六、包描述文件：歸納描述包的功能和設計概要。爲每一個包建立一個描述文件，命名爲package.html，與包的java文件放在一塊兒。

注：javadoc生成文檔時，會將該html文件的第一句放在package summary中，而把整個內容放在Overview summary中.

JAVADOC一些語法:
書寫格式:
/** <- 這裏必定要用兩個星號, 不然會被認爲是普通註釋的
* ........
*/
public int getCount() { .......
Javadoc只能爲public,protected兩種權限的類成員進行處理註釋文檔。固然也可使用-private參數強制進行處理, 咱們能夠在註釋中嵌入HTML個標記來豐富最後文檔的顯示, 由於Javadoc最後生成的文檔就是HTML.

/**
* 一些參數列表<p>
*
* @see 類名
* @see 完整類名
* @see 完整類名#方法
*
* @param 參數名說明
* @return 說明
* @exception 完整類名說明
* @deprecated
*
* @version 版本信息
* @author 做者名
*/
說明:
@see : 就是文檔中的參見xx 的條目, 其實就是超連接.

通常來講, 文檔有三種類型: 類註釋, 變量註釋, 方法註釋, 這三中類型的註釋除了均可以包含 @see 參數外, 其它所包含的參數是不一樣的.

1. 類註釋
類註釋是寫在類前面的, 用來講明類的一些狀況, 能夠包涵 @version,@author參數, 但Javadoc缺省狀況下不處理, 也就是說不在最後文檔中出現的, 爲了使用這些信息, 咱們能夠加入參數 -version和 -author來強制輸出到最後的文檔中.

2. 變量註釋
變量註釋寫在變量前面, 只能包含 @see 參數

3. 方法註釋
方法註釋能夠包括
@param : 參數名是指參數列表內的標識符, 說明就是一些解釋性質的文字, 能夠多行.
@return : 返回值的說明, 能夠多行
@exception : 完整類名應該明確指定一個違例類的名字，它是在其它某個地方定義好的。而說明則闡述爲何這種特殊類型的違例會在方法調用中出現。說明能夠多行
@deprecated : 指出一些舊功能已由改進過的新功能取代。該標記的做用是建議用戶沒必要再使用一種特定的功能，由於將來改版時可能摒棄這一功能。若將一個方法標記爲@deprecated，則使用該方法時會收到編譯器的警告。
css

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。