|
|
1. 安裝phpDocumentor（不推薦命令行安裝）
在http://manual.phpdoc.org/下載最新版本的phpDoc
放在web服務(wù)器目錄下使得通過瀏覽器可以訪問到
點(diǎn)擊files按鈕，選擇要處理的php文件或文件夾
還可以通過該指定該界面下的Files to ignore來忽略對(duì)某些文件的處理。
然后點(diǎn)擊output按鈕來選擇生成文檔的存放路徑和格式.
最后點(diǎn)擊create，phpdocumentor就會(huì)自動(dòng)開始生成文檔了。
2．如何寫php規(guī)范注釋
所有的文檔標(biāo)記都是在每一行的 * 后面以@開頭。如果在一段話的中間出來@的標(biāo)記，這個(gè)標(biāo)記將會(huì)被當(dāng)做普通內(nèi)容而被忽略掉。
@access 該標(biāo)記用于指明關(guān)鍵字的存取權(quán)限：private、public或proteced 使用范圍：class,function,var,define,module
@author 指明作者
@copyright 指明版權(quán)信息
@const 使用范圍：define 用來指明php中define的常量
@final 使用范圍：class,function,var 指明關(guān)鍵字是一個(gè)最終的類、方法、屬性，禁止派生、修改。
@global 指明在此函數(shù)中引用的全局變量
@name 為關(guān)鍵字指定一個(gè)別名。
@package 用于邏輯上將一個(gè)或幾個(gè)關(guān)鍵字分到一組。
@abstrcut 說明當(dāng)前類是一個(gè)抽象類
@param 指明一個(gè)函數(shù)的參數(shù)
@return 指明一個(gè)方法或函數(shù)的返回值
@static 指明關(guān)建字是靜態(tài)的。
@var 指明變量類型
@version 指明版本信息
@todo 指明應(yīng)該改進(jìn)或沒有實(shí)現(xiàn)的地方
@link 可以通過link指到文檔中的任何一個(gè)關(guān)鍵字
@ingore 用于在文檔中忽略指定的關(guān)鍵字
一些注釋規(guī)范
a.注釋必須是
/**
* XXXXXXX
*/
的形式
b.對(duì)于引用了全局變量的函數(shù)，必須使用glboal標(biāo)記。
c.對(duì)于變量，必須用var標(biāo)記其類型（int,string,bool...）
d.函數(shù)必須通過param和return標(biāo)記指明其參數(shù)和返回值
e.對(duì)于出現(xiàn)兩次或兩次以上的關(guān)鍵字，要通過ingore忽略掉多余的，只保留一個(gè)即可
f.調(diào)用了其他函數(shù)或類的地方，要使用link或其他標(biāo)記鏈接到相應(yīng)的部分，便于文檔的閱讀。
g.必要的地方使用非文檔性注釋（phpDOC無法識(shí)別的關(guān)鍵字前的注釋），提高代碼易讀性。
h.描述性內(nèi)容盡量簡(jiǎn)明扼要，盡可能使用短語而非句子。
i.全局變量，靜態(tài)變量和常量必須用相應(yīng)標(biāo)記說明
能夠被phpdoc識(shí)別的關(guān)鍵字：
Include
Require
include_once
require_once
define
function
global
class
3. 規(guī)范注釋的php代碼 :
<?php
/**
* 文件名(sample2.php)
*
* 功能描述（略）
*
* @author steve <http://www.jb51.NET>
* @version 1.0
* @package sample2
*/
/**
* 包含文件
*/
include_once 'sample3.php';
/**
* 聲明全局變量
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* 聲明全局常量
*/
define('NUM', 6);
/**
* 類名
*
* 類功能描述
*
* @package sample2
* @subpackage classes(如果是父類 就添加)
*/
class myclass {
/**
* 聲明普通變量
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* 創(chuàng)建構(gòu)造函數(shù) {@link $firstvar}
*/
function myclass() {
$this->firstvar = 7;
}
/**
* 定義函數(shù)
*
* 函數(shù)功能描述
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param1
* @param string $param2
* @return integer|string
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
}
?>
php技術(shù)：關(guān)于PHPDocument 代碼注釋規(guī)范的總結(jié)，轉(zhuǎn)載需保留來源！
鄭重聲明：本文版權(quán)歸原作者所有，轉(zhuǎn)載文章僅為傳播更多信息之目的，如作者信息標(biāo)記有誤，請(qǐng)第一時(shí)間聯(lián)系我們修改或刪除，多謝。
