程序師世界是廣大編程愛好者互助、分享、學習的平台,程序師世界有你更精彩!
首頁
編程語言
C語言|JAVA編程
Python編程
網頁編程
ASP編程|PHP編程
JSP編程
數據庫知識
MYSQL數據庫|SqlServer數據庫
Oracle數據庫|DB2數據庫
 程式師世界 >> 編程語言 >> JAVA編程 >> JAVA綜合教程 >> javadoc注釋規范,javadoc注釋

javadoc注釋規范,javadoc注釋

編輯:JAVA綜合教程

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

  1. 上一頁:
  2. 下一頁:
Copyright © 程式師世界 All Rights Reserved