PDP Document 代碼註釋規範

PHPDocumentor是一個用PHP寫的工具，對於有規範註釋的php程序，它可以快速生成具備相互參照,索引等功能的API文檔。老的版本是 phpdoc

1. 什麼是phpDocumentor ? 
PHPDocumentor是一個用PHP寫的工具，對於有規範註釋的php程序，它可以快速生成具備相互參照,索引等功能的API文檔。老的版本是 phpdoc，從1.3.0開始，改名爲phpDocumentor，新的版本加上了對php5語法的支持，同時，能夠經過在客戶端瀏覽器上操做生成文檔，文檔能夠轉換爲PDF,HTML,CHM幾種形式，很是的方便。 
PHPDocumentor工做時，會掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取須要分析的註釋，而後分析註釋中的專用的tag，生成 xml文件，接着根據已經分析完的類和模塊的信息，創建相應的索引，生成xml文件，對於生成的xml文件，使用定製的模板輸出爲指定格式的文件。 
2. 安裝phpDocumentor 
和其餘pear下的模塊同樣，phpDocumentor的安裝也分爲自動安裝和手動安裝兩種方式，兩種方式都很是方便： 
a． 經過pear 自動安裝 
在命令行下輸入 
pear install PhpDocumentor 
b． 手動安裝 
在http://manual.phpdoc.org/下載最新版本的PhpDocumentor（如今是1.4.0），把內容解壓便可。 
3．怎樣使用PhpDocumentor生成文檔 
命令行方式： 
在phpDocumentor所在目錄下，輸入 
Php –h 
會獲得一個詳細的參數表，其中幾個重要的參數以下： 
-f 要進行分析的文件名，多個文件用逗號隔開 
-d 要分析的目錄，多個目錄用逗號分割 
-t 生成的文檔的存放路徑 
-o 輸出的文檔格式，結構爲輸出格式：轉換器名：模板目錄。 
例如：phpdoc -o HTML:frames:earthli -f test.php -t docs 
Web界面生成 
在新的phpdoc中，除了在命令行下生成文檔外，還能夠在客戶端瀏覽器上操做生成文檔，具體方法是先把PhpDocumentor的內容放在apache目錄下使得經過瀏覽器能夠訪問到，訪問後顯示以下的界面： 
點擊files按鈕，選擇要處理的php文件或文件夾，還能夠經過該指定該界面下的Files to ignore來忽略對某些文件的處理。 
而後點擊output按鈕來選擇生成文檔的存放路徑和格式. 
最後點擊create，phpdocumentor就會自動開始生成文檔了，最下方會顯示生成的進度及狀態，若是成功，會顯示 
Total Documentation Time: 1 seconds 
done 
Operation Completed!! 
而後，咱們就能夠經過查看生成的文檔了，若是是pdf格式的，名字默認爲documentation.pdf。 
4．給php代碼添加規範的註釋 
PHPDocument是從你的源代碼的註釋中生成文檔，所以在給你的程序作註釋的過程，也就是你編制文檔的過程。 
從這一點上講，PHPdoc促使你要養成良好的編程習慣，儘可能使用規範，清晰文字爲你的程序作註釋，同時多多少少也避免了過後編制文檔和文檔的更新不一樣步的一些問題。 
在phpdocumentor中，註釋分爲文檔性註釋和非文檔性註釋。 
所謂文檔性註釋，是那些放在特定關鍵字前面的多行註釋，特定關鍵字是指可以被phpdoc分析的關鍵字，例如class，var等，具體的可參加附錄1. 
那些沒有在關鍵字前面或者不規範的註釋就稱做非文檔性註釋，這些註釋將不會被phpdoc所分析，也不會出如今你產生的api文當中。 
3.2如何書寫文檔性註釋: 
全部的文檔性註釋都是由/**開始的一個多行註釋，在phpDocumentor裏稱爲DocBlock, DocBlock是指軟件開發人員編寫的關於某個關鍵字的幫助信息，使得其餘人可以經過它知道這個關鍵字的具體用途，如何使用。 PhpDocumentor規定一個DocBlock包含以下信息： 
1. 功能簡述區 
2. 詳細說明區 
3. 標記tag 
文檔性註釋的第一行是功能描述區，正文通常是簡明扼要地說明這個類，方法或者函數的功能，功能簡述的正文在生成的文檔中將顯示在索引區。功能描述區的內容能夠經過一個空行或者 . 來結束 
在功能描述區後是一個空行，接着是詳細說明區,. 這部分主要是詳細說明你的API的功能，用途，若是可能，也能夠有用法舉例等等。在這部分，你應該着重闡明你的API函數或者方法的一般的用途，用法，而且指明是不是跨平臺的（若是涉及到），對於和平臺相關的信息，你要和那些通用的信息區別對待，一般的作法是另起一行，而後寫出在某個特定平臺上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者可以編寫相應的測試信息，好比邊界條件，參數範圍，斷點等等。 
以後一樣是一個空白行，而後是文檔的標記tag，指明一些技術上的信息，主要是最主要的是調用參數類型，返回值極其類型，繼承關係，相關方法/函數等等。 
關於文檔標記，詳細的請參考第四節:文檔標記。 
文檔註釋中還可使用例如<b> <code>這樣的標籤，詳細介紹請參考附錄二。 
下面是一個文檔註釋的例子 

複製代碼代碼以下:

/** 
* 函數add,實現兩個數的加法 
* 
* 一個簡單的加法計算，函數接受兩個數a、b，返回他們的和c 
* 
* @param int 加數 
* @param int 被加數 
* @return integer 
*/ 
function Add($a, $b) 
{ 
return $a+$b; 
}

生成文檔以下： 
Add 
integer Add( int $a, int $b) 
[line 45] 
函數add,實現兩個數的加法 
Constants 一個簡單的加法計算，函數接受兩個數a、b，返回他們的和c 
Parameters 
• int $a - 加數 
• int $b - 被加數 
5．文檔標記：  
文檔標記的使用範圍是指該標記能夠用來修飾的關鍵字，或其餘文檔標記。 
全部的文檔標記都是在每一行的 * 後面以@開頭。若是在一段話的中間出來@的標記，這個標記將會被當作普通內容而被忽略掉。 
@access 
使用範圍：class,function,var,define,module 
該標記用於指明關鍵字的存取權限：private、public或proteced 
@author 
指明做者 
@copyright 
使用範圍：class，function，var，define，module，use 
指明版權信息 
@deprecated 
使用範圍：class，function，var，define，module，constent，global，include 
指明不用或者廢棄的關鍵字 
@example 
該標記用於解析一段文件內容，並將他們高亮顯示。Phpdoc會試圖從該標記給的文件路徑中讀取文件內容 
@const 
使用範圍：define 
用來指明php中define的常量 
@final 
使用範圍：class,function,var 
指明關鍵字是一個最終的類、方法、屬性，禁止派生、修改。 
@filesource 
和example相似，只不過該標記將直接讀取當前解析的php文件的內容並顯示。 
@global 
指明在此函數中引用的全局變量 
@ingore 
用於在文檔中忽略指定的關鍵字 
@license 
至關於html標籤中的<a>,首先是URL，接着是要顯示的內容 
例如<a href=」http://www.baidu.com」>百度</a> 
能夠寫做 @license http://www.baidu.com 百度 
@link 
相似於license 
但還能夠經過link指到文檔中的任何一個關鍵字 
@name 
爲關鍵字指定一個別名。 
@package 
使用範圍：頁面級別的-> define，function，include 
類級別的->class，var，methods 
用於邏輯上將一個或幾個關鍵字分到一組。 
@abstrcut 
說明當前類是一個抽象類 
@param 
指明一個函數的參數 
@return 
指明一個方法或函數的返回指 
@static 
指明關建字是靜態的。 
@var 
指明變量類型 
@version 
指明版本信息 
@todo 
指明應該改進或沒有實現的地方 
@throws 
指明此函數可能拋出的錯誤異常,極其發生的狀況 
上面提到過，普通的文檔標記標記必須在每行的開頭以@標記，除此以外，還有一種標記叫作inline tag,用{@}表示，具體包括如下幾種： 
{@link} 
用法同@link 
{@source} 
顯示一段函數或方法的內容 
6．一些註釋規範  
a.註釋必須是 
/** 
* XXXXXXX 
*/ 
的形式 
b.對於引用了全局變量的函數，必須使用glboal標記。 
c.對於變量，必須用var標記其類型（int,string,bool...） 
d.函數必須經過param和return標記指明其參數和返回值 
e.對於出現兩次或兩次以上的關鍵字，要經過ingore忽略掉多餘的，只保留一個便可 
f.調用了其餘函數或類的地方，要使用link或其餘標記連接到相應的部分，便於文檔的閱讀。 
g.必要的地方使用非文檔性註釋，提升代碼易讀性。 
h.描述性內容儘可能簡明扼要，儘量使用短語而非句子。 

i.全局變量，靜態變量和常量必須用相應標記說明 

7. 總結 
phpDocumentor是一個很是強大的文檔自動生成工具，利用它能夠幫助咱們編寫規範的註釋，生成易於理解，結構清晰的文檔，對咱們的代碼升級，維護,移交等都有很是大的幫助。 
關於phpDocumentor更爲詳細的說明，能夠到它的官方網站 
http://manual.phpdoc.org/查閱 
8．附錄 
附錄1: 
可以被phpdoc識別的關鍵字： 
Include 
Require 
include_once 
require_once 
define 
function 
global 
class 
附錄2 
文檔中可使用的標籤 
<b> 
<code> 
<br> 
<kdb> 
<li> 
<pre> 
<ul> 
<samp> 
<var> 
附錄三： 
一段含有規範註釋的php代碼 

複製代碼代碼以下:

<?php 
/** 
* Sample File 2, phpDocumentor Quickstart 
* 
* This file demonstrates the rich information that can be included in 
* in-code documentation through DocBlocks and tags. 
* @author Greg Beaver <cellog@php.net> 
* @version 1.0 
* @package sample 
*/ 
// sample file #1 
/** 
* Dummy include value, to demonstrate the parsing power of phpDocumentor 
*/ 
include_once 'sample3.php'; 
/** 
* Special global variable declaration DocBlock 
* @global integer $GLOBALS['_myvar'] 
* @name $_myvar 
*/ 
$GLOBALS['_myvar'] = 6; 
/** 
* Constants 
*/ 
/** 
* first constant 
*/ 
define('testing', 6); 
/** 
* second constant 
*/ 
define('anotherconstant', strlen('hello')); 
/** 
* A sample function docblock 
* @global string document the fact that this function uses $_myvar 
* @staticvar integer $staticvar this is actually what is returned 
* @param string $param1 name to declare 
* @param string $param2 value of the name 
* @return integer 
*/ 
function firstFunc($param1, $param2 = 'optional') 
{ 
static $staticvar = 7; 
global $_myvar; 
return $staticvar; 
} 
/** 
* The first example class, this is in the same package as the 
* procedural stuff in the start of the file 
* @package sample 
* @subpackage classes 
*/ 
class myclass { 
/** 
* A sample private variable, this can be hidden with the --parseprivate 
* option 
* @access private 
* @var integer|string 
*/ 
var $firstvar = 6; 
/** 
* @link http://www.example.com Example link 
* @see myclass() 
* @uses testing, anotherconstant 
* @var array 
*/ 
var $secondvar = 
array( 
'stuff' => 
array( 
6, 
17, 
'armadillo' 
), 
testing => anotherconstant 
); 
/** 
* Constructor sets up { @link $firstvar} 
*/ 
function myclass() 
{ 
$this->firstvar = 7; 
} 
/** 
* Return a thingie based on $paramie 
* @param boolean $paramie 
* @return integer|babyclass 
*/ 
function parentfunc($paramie) 
{ 
if ($paramie) { 
return 6; 
} else { 
return new babyclass; 
} 
} 
} 
/** 
* @package sample1 
*/ 
class babyclass extends myclass { 
/** 
* The answer to Life, the Universe and Everything 
* @var integer 
*/ 
var $secondvar = 42; 
/** 
* Configuration values 
* @var array 
*/ 
var $thirdvar; 
/** 
* Calls parent constructor, then increments { @link $firstvar} 
*/ 
function babyclass() 
{ 
parent::myclass(); 
$this->firstvar++; 
} 
/** 
* This always returns a myclass 
* @param ignored $paramie 
* @return myclass  */  function parentfunc($paramie)  {  return new myclass;  }  }  ?>