一 Java 文檔
// 注釋一行
/* */ 注釋若干行
/** */ 注釋若干行並寫入 javadoc 文檔
通常這種注釋的多行寫法如下
/**
*
*
*/
javadoc d 文檔存放目錄 author version 源文件名java
這條命令編譯一個名為 源文件名java的 java 源文件並將生成的文檔存放在文檔存放目錄指定的目錄下生成的文檔中 l 就是文檔的首頁author 和 version 兩個選項可以省略
二 文檔注釋的格式
文檔和文檔注釋的格式化
生成的文檔是 HTML 格式而這些 HTML 格式的標識符並不是 javadoc 加的而是我們在寫注釋的時候寫上去的
比如需要換行時不是敲入一個回車符而是寫入 <br>如果要分段就應該在段前寫入 <p>
文檔注釋的正文並不是直接復制到輸出文件 (文檔的 HTML 文件)而是讀取每一行後刪掉前導的 * 號及 * 號以前的空格再輸入到文檔的如
/**
* This is first line <br>
***** This is second line <br>
This is third line
*/
文檔注釋的三部分
先舉例如下
/**
* show 方法的簡述
* <p>show 方法的詳細說明第一行<br>
* show 方法的詳細說明第二行
* @param b true 表示顯示false 表示隱藏
* @return 沒有返回值
*/
public void show(boolean b) {
frameshow(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 下有兩個包若干類如下
fancyEditor
fancyTest
fancyeditorECommand
fancyeditorEDocument
fancyeditorEView
可以直接編譯類
javadoc fancy\Testjava fancy\Editorjava fancy\editor\ECommandjava fancy\editor\EDocumentjava fancy\editor\EViewjava
也可以是給出包名作為編譯參數如javadoc fancy fancyeditor
可以自己看看這兩種方法的區別
到此為止javadoc就簡單介紹完了想要用好她還是要多用多參考標准java代碼
Java代碼規范
注釋
@author LEI
@version
注釋文檔的格式
注釋文檔將用來生成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);
}
前兩行為描述描述完畢後由@符號起頭為塊標記注視
注釋的種類
文件頭注釋
文件頭注釋以 /*開始以*/結束需要注明該文件創建時間文件名命名空間信息
例如
/*
* Created on
* /
類接口注釋
類接口的注釋采用 /** … */描述部分用來書寫該類的作用或者相關信息塊標記部分必須注明作者和版本
例如
/**Title: XXXX DRIVER
*Description: XXXX DRIVER
*Copyright: Copyright (c)
*Company:XXXX有限公司
*
* @author Java Development Group
* @version
*/
例如
/**
* A class representing a window on the screen
* For example:
*
* Window win = new Window(parent);
* winshow();
*
*
* @author Sami Shaio
* @version %I% %G%
* @see javaawtBaseWindow
* @see javaawtButton
*/
class Window extends BaseWindow {
}
構造函數注釋
構造函數注釋采用 /** … */描述部分注明構造函數的作用不一定有塊標記部分
例如
/**
* 默認構造函數
*/
有例如
/**
* 帶參數構造函數初始化模式名名稱和數據源類型
*
* @param schema
* Ref 模式名
* @param name
* Ref 名稱
* @param type
* byVal 數據源類型
*/
域注釋
域注釋可以出現在注釋文檔裡面也可以不出現在注釋文檔裡面用/** … */的域注釋將會被認為是注釋文檔熱出現在最終生成的HTML報告裡面而使用/* … */的注釋會被忽略
例如
/* 由於triger和表用一個DMSource所以要區分和表的遷移成功標記 */
boolean isTrigerSuccess = false;
又例如
/** 由於triger和表用一個DMSource所以要區分和表的遷移成功標記 */
boolean isTrigerSuccess = false;
再例如
/**
* The Xcoordinate of the component
*
* @see #getLocation()
*/
int x = ;
方法注釋
方法注釋采用 /** … */描述部分注明方法的功能塊標記部分注明方法的參數返回值異常等信息例如
/**
* 設置是否有外碼約束
*
* @param conn
* Connection 與數據庫的連接
*/
定義注釋
規則同域注釋
From:http://tw.wingwit.com/Article/program/Java/hx/201311/25889.html
