javadoc注釋規範，javadoc注釋

javadoc注釋規範，javadoc注釋

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

} 

}

 

轉載自http://kelaocai.iteye.com/blog/227822