javadoc 和 javadoc註釋規範

javadoc是Sun公司提供的一個技術，它從程序源代碼中抽取類、方法、成員等註釋造成一個和源代碼配套的API幫助文檔。

javadoc命令是用來生成本身 API文檔的，使用方式：在dos中在目標文件所在目錄輸入javadoc +文件名.java。

 

標籤	說明	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}幾個不經常使用的標籤，因爲不常使用，咱們展開敘述，感興趣的讀者能夠查看幫助文檔。

 

 

javadoc作註釋 一. Java 文檔 // 註釋一行 /* ...... */ 註釋若干行 /** ...... */ 註釋若干行，並寫入 javadoc 文檔 一般這種註釋的多行寫法以下： /** * ......... * ......... */ javadoc -d 文檔存放目錄 -author -version 源文件名.java 這條命令編譯一個名爲 「源文件名.java」的 java 源文件，並將生成的文檔存放在「文檔存放目錄」指定的目錄下，生成的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩個選項能夠省略。 二. 文檔註釋的格式 1. 文檔和文檔註釋的格式化 生成的文檔是 HTML 格式，而這些 HTML 格式的標識符並非 javadoc 加的，而是咱們在寫註釋的時候寫上去的。 好比，須要換行時，不是敲入一個回車符，而是寫入 <br>，若是要分段，就應該在段前寫入 <p>。 文檔註釋的正文並非直接複製到輸出文件 (文檔的 HTML 文件)，而是讀取每一行後，刪掉前導的 * 號及 * 號之前的空格，再輸入到文檔的。如 /** * This is first line. <br> ***** This is second line. <br> This is third line. */ 2. 文檔註釋的三部分 先舉例以下 /** * show 方法的簡述. * <p>show 方法的詳細說明第一行<br> * show 方法的詳細說明第二行 * @param b true 表示顯示，false 表示隱藏 * @return 沒有返回值 */ public void show(boolean b) { frame.show(b); } 第一部分是簡述。文檔中，對於屬性和方法都是先有一個列表，而後纔在後面一個一個的詳細的說明 簡述部分寫在一段文檔註釋的最前面，第一個點號 (.) 以前 (包括點號)。換句話說，就是用第一個點號分隔文檔註釋，以前是簡述，以後是第二部分和第三部分。 第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明，在格式上沒有什麼特殊的要求，能夠包含若干個點號。 * show 方法的簡述. * <p>show 方法的詳細說明第一行<br> * show 方法的詳細說明第二行 簡述也在其中。這一點要記住了 第三部分是特殊說明部分。這部分包括版本說明、參數說明、返回值說明等。 * @param b true 表示顯示，false 表示隱藏 * @return 沒有返回值 三. 使用 javadoc 標記 javadoc 標記由「@」及其後所跟的標記類型和專用註釋引用組成 javadoc 標記有以下一些： @author 標明開發該類模塊的做者 @version 標明該類模塊的版本 @see 參考轉向，也就是相關主題 @param 對方法中某參數的說明 @return 對方法返回值的說明 @exception 對方法可能拋出的異常進行說明 @author 做者名 @version 版本號 其中，@author 能夠屢次使用，以指明多個做者，生成的文檔中每一個做者之間使用逗號 (,) 隔開。@version 也可使用屢次，只有第一次有效 使用 @param、@return 和 @exception 說明方法 這三個標記都是隻用於方法的。@param 描述方法的參數，@return 描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法以下： @param 參數名 參數說明 @return 返回值說明 @exception 異常類名 說明 四. javadoc 命令 用法： 　　javadoc [options] [packagenames] [sourcefiles] 選項： -public 僅顯示 public 類和成員 -protected 顯示 protected/public 類和成員 (缺省) -package 顯示 package/protected/public 類和成員 -private 顯示全部類和成員 -d <directory> 輸出文件的目標目錄 -version 包含 @version 段 -author 包含 @author 段 -splitindex 將索引分爲每一個字母對應一個文件 -windowtitle <text> 文檔的瀏覽器窗口標題 javadoc 編譯文檔時能夠給定包列表，也能夠給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類以下： 　　fancy.Editor 　　fancy.Test 　　fancy.editor.ECommand 　　fancy.editor.EDocument 　　fancy.editor.EView 能夠直接編譯類： javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java 也能夠是給出包名做爲編譯參數，如：javadoc fancy fancy.editor 能夠本身看看這兩種方法的區別 到此爲止javadoc就簡單介紹完了，想要用好她仍是要多用，多參考標準java代碼 Java代碼規範 --註釋 @author LEI @version 1.10 2005-09-01 1 註釋文檔的格式 註釋文檔將用來生成HTML格式的代碼報告，因此註釋文檔必須書寫在類、域、構造函數、方法、定義以前。註釋文檔由兩部分組成——描述、塊標記。 例如： /** * The doGet method of the servlet. * This method is called when a form has its tag value method equals to get. * * @param request * the request send by the client to the server * @param response * the response send by the server to the client * @throws ServletException * if an error occurred * @throws IOException * if an error occurred */ public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request, response); } 前兩行爲描述，描述完畢後，由@符號起頭爲塊標記注視。 2 註釋的種類 2.1 文件頭註釋 文件頭註釋以 /*開始，以*/結束，須要註明該文件建立時間，文件名，命名空間信息。 例如： /* * Created on 2005-7-2 * / 2.2 類、接口註釋 類、接口的註釋採用 /** … */，描述部分用來書寫該類的做用或者相關信息，塊標記部分必須註明做者和版本。 例如： /**Title: XXXX DRIVER 3.0 *Description: XXXX DRIVER 3.0 *Copyright: Copyright (c) 2003 *Company:XXXX有限公司 * * @author Java Development Group * @version 3.0 */ 例如： /** * A class representing a window on the screen. * For example: * * Window win = new Window(parent); * win.show(); * * * @author Sami Shaio * @version %I%, %G% * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { ... } 2.3 構造函數註釋 構造函數註釋採用 /** … */，描述部分註明構造函數的做用，不必定有塊標記部分。 例如： /** * 默認構造函數 */ 有例如： /** * 帶參數構造函數,初始化模式名,名稱和數據源類型 * * @param schema * Ref 模式名 * @param name * Ref 名稱 * @param type * byVal 數據源類型 */ 2.4 域註釋 域註釋能夠出如今註釋文檔裏面，也能夠不出如今註釋文檔裏面。用/** … */的域註釋將會被認爲是註釋文檔熱出如今最終生成的HTML報告裏面，而使用/* … */的註釋會被忽略。 例如： /* 因爲triger和表用一個DMSource，因此要區分和表的遷移成功標記 */ boolean isTrigerSuccess = false; 又例如： /** 因爲triger和表用一個DMSource，因此要區分和表的遷移成功標記 */ boolean isTrigerSuccess = false; 再例如： /** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732; 2.5 方法註釋 方法註釋採用 /** … */，描述部分註明方法的功能，塊標記部分註明方法的參數，返回值，異常等信息。例如： /** * 設置是否有外碼約束 * * @param conn * Connection 與數據庫的鏈接 */ 2.6 定義註釋 規則同域註釋。 3 註釋塊標記 3.1 標記的順序 塊標記將採用以下順序： … * * @param (classes, interfaces, methods and constructors only) * @return (methods only) * @exception (@throws is a synonym added in Javadoc 1.2) * @author (classes and interfaces only, required) * @version (classes and interfaces only, required. See footnote 1) * @see * @since * @serial (or @serialField or @serialData) * @deprecated (see How and When To Deprecate APIs) * … 一個塊標記能夠根據須要重複出現屢次，屢次出現的標記按照以下順序： @author 按照時間前後順序（chronological） @param 按照參數定義順序（declaration） @throws 按照異常名字的字母順序（alphabetically） @see 按照以下順序： @see #field @see #Constructor(Type, Type...) @see #Constructor(Type id, Type id...) @see #method(Type, Type,...) @see #method(Type id, Type, id...) @see Class @see Class#field @see Class#Constructor(Type, Type...) @see Class#Constructor(Type id, Type id) @see Class#method(Type, Type,...) @see Class#method(Type id, Type id,...) @see package.Class @see package.Class#field @see package.Class#Constructor(Type, Type...) @see package.Class#Constructor(Type id, Type id) @see package.Class#method(Type, Type,...) @see package.Class#method(Type id, Type, id) @see package 3.2 標記介紹 3.2.1 @param標記 @param後面空格後跟着參數的變量名字（不是類型），空格後跟着對該參數的描述。 在描述中第一個名字爲該變量的數據類型，表示數據類型的名次前面能夠有一個冠詞如：a,an,the。若是是int類型的參數則不須要註明數據類型。例如： … * @param ch the char 用用來…… * @param _image the image 用來…… * @param _num 一個數字…… … 對於參數的描述若是隻是一短語，最好不要首字母大寫，結尾也不要句號。 對於參數的描述是一個句子，最好不要首字母大寫，若是出現了句號這說明你的描述不止一句話。若是非要首字母大寫的話，必須用句號來結束句子。（英文的句號） 公司內部添加ByRef和ByVal兩個標記，例如： * @param _image the image ByRef 用來…… 說明該參數是引用傳遞（指針），ByVal能夠省略，表示是值傳遞。 3.2.2 @return標記 返回爲空（void）的構造函數或者函數，@return能夠省略。 若是返回值就是輸入參數，必須用與輸入參數的@param相同的描述信息。 必要的時候註明特殊條件寫的返回值。 3.2.3 @throws 標記 @throws之前使用的是@exception。 @throws的內容必須在函數的throws部分定義。 3.2.4 @author標記 類註釋標記。 函數註釋裏面能夠不出現@author。 3.2.5 @version 類註釋標記。 函數註釋裏面能夠不出現@version 3.2.6 @since 類註釋標記。 標明該類能夠運行的JDK版本 例如： @since JDK1.2 3.2.7 @deprecated 因爲某種緣由而被宣佈將要被廢棄的方法。 /** * @deprecated As of JDK 1.1, replaced by * setBounds * @see #setBounds(int,int,int,int) */ 3.2.8 @link標記 語法：{@link package.class#member label} Label爲連接文字。 package.class#member將被自動轉換成指向package.class的member文件的URL。 4 HTML代碼的使用 在註釋描述部分可使用HTML代碼。 … 表示段落     * …. 表示自動標號 5 註釋示例 /** * Graphics is the abstract base class for all graphics contexts * which allow an application to draw onto components realized on * various devices or onto off-screen images. * A Graphics object encapsulates the state information needed * for the various rendering operations that Java supports. This * state information includes: * # * The Component to draw on # * A translation origin for rendering and clipping coordinates # * The current clip # * The current color # * The current font # * The current logical pixel operation function (XOR or Paint) # * The current XOR alternation color * (see setXORMode) * * * Coordinates are infinitely thin and lie between the pixels of the * output device. * Operations which draw the outline of a figure operate by traversing * along the infinitely thin path with a pixel-sized pen that hangs * down and to the right of the anchor point on the path. * Operations which fill a figure operate by filling the interior * of the infinitely thin path. * Operations which render horizontal text render the ascending * portion of the characters entirely above the baseline coordinate. * * Some important points to consider are that drawing a figure that * covers a given rectangle will occupy one extra row of pixels on * the right and bottom edges compared to filling a figure that is * bounded by that same rectangle. * Also, drawing a horizontal line along the same y coordinate as * the baseline of a line of text will draw the line entirely below * the text except for any descenders. * Both of these properties are due to the pen hanging down and to * the right from the path that it traverses. * * All coordinates which appear as arguments to the methods of this * Graphics object are considered relative to the translation origin * of this Graphics object prior to the invocation of the method. * All rendering operations modify only pixels which lie within the * area bounded by both the current clip of the graphics context * and the extents of the Component used to create the Graphics object. * * @author Sami Shaio * @author Arthur van Hoff * @version %I%, %G% * @since 1.0 */ public abstract class Graphics { /** * Draws as much of the specified image as is currently available * with its northwest corner at the specified coordinate (x, y). * This method will return immediately in all cases, even if the * entire image has not yet been scaled, dithered and converted * for the current output device. * * If the current output representation is not yet complete then * the method will return false and the indicated * {@link ImageObserver} object will be notified as the * conversion process progresses. * * @param img the image to be drawn * @param x the x-coordinate of the northwest corner * of the destination rectangle in pixels * @param y the y-coordinate of the northwest corner * of the destination rectangle in pixels * @param observer the image observer to be notified as more * of the image is converted. May be * null * @return true if the image is completely * loaded and was painted successfully; * false otherwise. * @see Image * @see ImageObserver * @since 1.0 */ public abstract boolean drawImage(Image img, int x, int y, ImageObserver observer); /** * Dispose of the system resources used by this graphics context. * The Graphics context cannot be used after being disposed of. * While the finalization process of the garbage collector will * also dispose of the same system resources, due to the number * of Graphics objects that can be created in short time frames * it is preferable to manually free the associated resources * using this method rather than to rely on a finalization * process which may not happen for a long period of time. * * Graphics objects which are provided as arguments to the paint * and update methods of Components are automatically disposed * by the system when those methods return. Programmers should, * for efficiency, call the dispose method when finished using * a Graphics object only if it was created directly from a * Component or another Graphics object. * * @see #create(int, int, int, int) * @see #finalize() * @see Component#getGraphics() * @see Component#paint(Graphics) * @see Component#update(Graphics) * @since 1.0 */ public abstract void dispose(); /** * Disposes of this graphics context once it is no longer * referenced. * * @see #dispose() * @since 1.0 */ public void finalize() { dispose(); } }