javadoc註釋規範

javahtml

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(); 
} 
}