PDP Document程式碼註解規範

1. 什麼是phpDocumentor ?<br>PHPDocumentor是一個用PHP寫的工具，對於有規範註釋的php程序，它能夠快速產生具有相互參照,索引等功能的API文檔。舊的版本是phpdoc，從1.3.0開始，更名為phpDocumentor，新的版本加上了對php5語法的支持，同時，可以透過在客戶端瀏覽器上操作生成文檔，文檔可以轉換為PDF,HTML, CHM幾種形式，非常的方便。 <br>PHPDocumentor工作時，會掃描指定目錄下面的php源代碼，掃描其中的關鍵字，截取需要分析的註釋，然後分析註釋中的專用的tag，生成xml文件，接著根據已經分析完的類和模組的訊息，建立對應的索引，產生xml文件，對於產生的xml文件，使用自訂的範本輸出為指定格式的文件。 <br>2. 安裝phpDocumentor<br> 和其他pear下的模組一樣，phpDocumentor的安裝也分為自動安裝和手動安裝兩種方式，兩種方式都非常方便：<br>a． 透過pear 自動安裝<br>在命令列下輸入 <br>pear install PhpDocumentor<br>b． 手動安裝<br>在http://manual.phpdoc.org/下載最新版本的PhpDocumentor（現在是1.4.0），把內容解壓縮即可。 <br>3．如何使用PhpDocumentor產生文件<br>命令列方式：<br>在phpDocumentor所在目錄下，輸入<br>Php –h<br>會得到一個詳細的參數表，其中幾個重要的參數如下：<br>-f 要進行分析的文件名，多個檔案以逗號隔開<br>-d 要分析的目錄，多個目錄以逗號分割<br>-t 產生的文件的存放路徑<br>-o 輸出的文件格式，結構為輸出格式：轉換器名稱：範本目錄。 <br>例如：phpdoc -o HTML:frames:earthli -f test.php -t docs<br>Web介面產生<br>在新的phpdoc中，除了在命令列下產生文件外，還可以在客戶端瀏覽器上操作生成文檔，具體方法是先把PhpDocumentor的內容放在apache目錄下使得透過瀏覽器可以存取到，訪問後顯示如下的介面：<br>點擊files按鈕，選擇要處理的php檔案或資料夾，還可以透過該指定該介面下的Files to ignore來忽略某些檔案的處理。 <br>接著點選output按鈕選擇產生文件的存放路徑和格式.<br>最後點選create，phpdocumentor就會自動開始產生文件了，最下方會顯示產生的進度及狀態，如果成功，會顯示<br>Total Documentation Time: 1 seconds<br>done<br>Operation Completed!!<br>然後，我們就可以透過檢視產生的文件了，如果是pdf格式的，名字預設為documentation.pdf。 <br>4．為php程式碼新增規範的註解<br>PHPDocument是從你的原始碼的註解中產生文檔，因此在給你的程式做註解的過程，也就是你編製文檔的過程。 <br>從這一點上講，PHPdoc促使你要養成良好的程式設計習慣，盡量使用規範，清晰文字為你的程式做註釋，同時多多少少也避免了事後編製文件和文件的更新不同步的一些問題。 <br> 在phpdocumentor中，註解分為文檔性註解和非文檔性註解。 <br>所謂文檔性註釋，是那些放在特定關鍵字前面的多行註釋，特定關鍵字是指能夠被phpdoc分析的關鍵字，例如class，var等，具體的可參加附錄1.<br>那些沒有在關鍵字前面或不規範的註釋就稱為非文檔性註釋，這些註釋將不會被phpdoc分析，也不會出現在你產生的api文當中。 <br>3.2如何書寫文檔性註釋:<br> 所有的文檔性註釋都是由/**開始的一個多行註釋，在phpDocumentor裡稱為DocBlock, DocBlock是指軟體開發人員編寫的關於某個關鍵字的幫助信息，使得其他人能夠透過它知道這個關鍵字的具體用途，如何使用。 PhpDocumentor規定一個DocBlock包含以下資訊：<br>1. 功能簡述區<br>2. 詳細說明區<br>3. 標記tag<br>文檔性註釋的第一行是功能描述區，正文一般是簡明扼要地說明這個類，方法或函數的功能，功能簡述的正文在產生的文件中將顯示在索引區。功能描述區的內容可以透過一個空行或. 來結束<br>在功能描述區後是一個空行，接著是詳細說明區,. 這部分主要是詳細說明你的API的功能，用途，如果可能，也可以有用法舉例等等。在這部分，你應該專注於闡明你的API函數或方法的通常的用途，用法，並且指明是否是跨平台的（如果涉及到），對於和平台相關的信息，你要和那些通用的信息區別對待，通常的做法是另起一行，然後寫出在某個特定平台上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者能夠編寫相應的測試信息，比如邊界條件，參數範圍，斷點等等。<br>之後同樣是一個空白行，然後是文檔的標記tag，指明一些技術上的信息，主要是最主要的是調用參數類型，返回值極其類型，繼承關係，相關方法/函數等等。 <br>關於文檔標記，詳細的請參考第四節:文檔標記。 <br>文件註解中也可以使用例如 這樣的標籤，詳細介紹請參考附錄二。 &lt;br&gt;下面是一個文件註解的範例&lt;br&gt;/**&lt;br&gt;* 函數add,實現兩個數的加法&lt;br&gt;*&lt;br&gt;* 一個簡單的加法計算，函數接受兩個數a、b，回傳他們的和c&lt;br&gt;* &lt;br&gt;* @param int 加數&lt;br&gt;* @param int 被加數&lt;br&gt;* @return integer &lt;br&gt;*/&lt;br&gt;function Add($a, $b)&lt;br&gt;{&lt;br&gt; return $a+$b;&lt;br&gt;}&lt;br&gt;產生文件如下：&lt;br&gt;Add&lt;br&gt;integer Add( int $a, int $b) &lt;br&gt;[line 45]&lt;br&gt;函數add,實現兩個數的加法&lt;br&gt;Constants 一個簡單的加法計算，函數接受兩個數a、b，返回他們的和c&lt;br&gt;Parameters&lt;br&gt;? int $ a - 加數&lt;br&gt;? int $b - 被加數&lt;br&gt;5．文檔標記：&lt;br&gt;文檔標記的使用範圍是指該標記可以用來修飾的關鍵字，或其他文檔標記。 &lt;br&gt;所有的文檔標記都是在每一行的 * 後面以@開頭。如果在一段話的中間出來@的標記，這個標記將會被當做普通內容而被忽略掉。 &lt;br&gt;@access&lt;br&gt;使用範圍：class,function,var,define,module&lt;br&gt;此標記用於指明關鍵字的存取權限：private、public或proteced&lt;br&gt;@author&lt;br&gt;指明作者&lt;br&gt;@copyright&lt;br&gt;使用範圍：class，function ，var，define，module，use&lt;br&gt;指明版權資訊&lt;br&gt;@deprecated&lt;br&gt;使用範圍：class，function，var，define，module，constent，global，<strong>include</strong>&lt;br&gt;指明不用或廢棄的關鍵字&lt;br&gt;@example&lt;br&gt;@example<strong>@example</strong>@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example<strong>@example</strong>@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example&lt;br&gt;@example<strong>@example用於解析一段文件內容，並將他們高亮顯示。 Phpdoc會試圖從該標記給的檔案路徑中</strong>讀取檔案&lt;br&gt;內容<strong>@const</strong>使用範圍：define&lt;br&gt;用來指明php中define的常數&lt;br&gt; @final&lt;br&gt;使用範圍：class,function,var&lt;br&gt;指明關鍵字是一個最終的類別、方法、屬性，禁止派生、修改。 &lt;br&gt;@filesource&lt;br&gt;和example類似，只不過該標記將直接讀取目前解析的php檔案的內容並顯示。 &lt;br&gt;@global<strong>指明在此函數中引用的</strong>全域變數&lt;br&gt;&lt;br&gt;@ingore&lt;br&gt;用於在文件中忽略指定的關鍵字&lt;br&gt;@license&lt;br&gt;相當於html標籤中的<a>,首先是URL，接著是要顯示的內容&lt;br&gt;例如</a><a href="%E2%80%9Dhttp://www.baidu.com%E2%80%9D">&lt;br&gt;百度&lt;br&gt;</a>&lt;br&gt;可以寫@license http://www.baidu.com &lt;br&gt;百度&lt;br&gt;&lt;br&gt;@link&lt;br&gt;類似於license&lt;br&gt;但也可以透過link指到文件中的任何一個關鍵字&lt;br&gt;@name&lt;br&gt;為關鍵字指定一個別名。 &lt;br&gt;@package&lt;br&gt;使用範圍：頁面層級的-> define，function，&lt;br&gt;include&lt;br&gt;&lt;br&gt; 類別層級的->class，var，methods&lt;br&gt;用於邏輯上將一個或幾個關鍵字分到一組。 &lt;br&gt;@abstrcut&lt;br&gt;說明目前類別是抽象類別&lt;br&gt;@param&lt;br&gt;指明一個函數的參數&lt;br&gt;@return&lt;br&gt;指明一個方法或函數的回傳指&lt;br&gt;@static&lt;br&gt;指明關建字是靜態的。 <strong>@var</strong>指明變數類型&lt;br&gt;@version&lt;br&gt;指明版本資訊&lt;br&gt;@todo&lt;br&gt;指明應該改進或沒有實現的地方&lt;br&gt;@throws&lt;br&gt;指明此函數可能拋出的錯誤異常,極其發生的情況&lt;br&gt;上面提到過，普通的文檔標記標記必須在每行的開頭以@標記，除此之外，還有一種標記叫做inline tag,用{@}表示，具體包括以下幾種：<strong>{@link}</strong>用法同@link <strong>{@source}</strong>顯示一段函數或方法的內容&lt;br&gt;6．一些註釋規範&lt;br&gt;a.註釋必須是🎜/**🎜* XXXXXXX🎜*/🎜的形式🎜b.對於引用了🎜全局變數🎜的函數，必須使用glboal標記。 🎜c.對於變量，必須用var標記其類型（int,string,bool...）🎜d.函數必須透過param和return標記指明其參數和返回值🎜e.對於出現兩次或兩次以上的關鍵字，要透過ingore忽略掉多餘的，只保留一個即可🎜f.調用了其他函數或類的地方，要使用link或其他標記鏈接到相應的部分，便於文檔的閱讀。 🎜g.必要的地方使用非文檔性註釋，提高程式碼易讀性。 🎜h.描述性內容盡量簡明扼要，盡可能使用短語而非句子。 🎜i.🎜全域變數🎜，🎜靜態變數🎜和常數必須用相應標記說明🎜7. 總結🎜phpDocumentor是一個非常強大的文檔自動生成工具，利用它可以幫助我們編寫規範的註釋，生成易於理解，結構清晰的文檔，對我們的程式碼升級，維護,移交等都有非常大的幫助。&lt;br&gt;關於phpDocumentor更為詳細的說明，可以到它的官方網站&lt;br&gt;http://manual.phpdoc.org/查閱&lt;br&gt;8．附錄&lt;br&gt;附錄1:&lt;br&gt;能夠被phpdoc辨識的關鍵字：&lt;br&gt;<strong>include</strong>&lt;br&gt;<strong>require</strong>&lt;br&gt;<strong>include</strong>_once&lt;br&gt;可以使用的標籤<strong><b> </b></strong><code> &lt;br&gt;&lt;br&gt; &lt;br&gt;<kdb>&lt;br&gt;<li> &lt;br&gt;<pre class="brush:php;toolbar:false">&lt;br&gt;</pre> <ul> &lt;br&gt;<samp>&lt;br&gt;<var>&lt;br&gt;附錄三：&lt;br&gt; ?php&lt;br&gt;/**&lt;br&gt;* 範例文件 2，phpDocumentor 快速入門&lt;br&gt;* &lt;br&gt;* 此文件示範了可以透過 DocBlocks 和標籤&lt;br&gt;include&lt;br&gt;d 包含&lt;br&gt;* 程式碼內文件的豐富資訊。 &lt;br&gt;* @author Greg Beaver <cellog> ;&lt;br&gt;* @版本 1.0&lt;br&gt;* @包裝樣本&lt;br&gt;*/&lt;br&gt;// sample file #1&lt;br&gt;/**<strong>* Dummy </strong>include&lt;br&gt;值，展示phpDocumentor&lt;br&gt;的解析能力*/&lt;br&gt;&lt;br&gt;include&lt;br&gt;_once 'sample3.php';&lt;br&gt;/**&lt;br&gt;* 特殊全域變數宣告 DocBlock&lt;br&gt;* @global integer $GLOBALS['_myvar'] <strong>* @name $_myvar</strong>*/ &lt;br&gt;$GLOBALSALS ['_myvar'] = 6;&lt;br&gt;/**<strong>* 常數</strong>*/&lt;br&gt;/**&lt;br&gt;* 第一個常數&lt;br&gt;*/&lt;br&gt;define('testing', 6);&lt;br&gt;/**&lt;br&gt;* 第二個常數&lt;br&gt;*/&lt;br&gt;define('anotherconstant ', strlen('hello'));&lt;br&gt;/**&lt;br&gt;* 範例函數docblock&lt;br&gt;* @global string 記錄了該函數使用$_myvar 的事實&lt;br&gt;* @staticvar 整型$staticvar 這實際上是傳回的內容&lt;br&gt;* @param string $param1 要宣告的名稱&lt;br&gt;* @param string $param2名稱的值&lt;br&gt;* @return 整數&lt;br&gt;*/&lt;br&gt;function firstFunc($param1, $param2 = 'optional')&lt;br&gt;{&lt;br&gt; static $staticvar = 7;&lt;br&gt; global $_myvar{&lt;br&gt; static $staticvar = 7;&lt;br&gt; global $_myvar; staticvar;&lt;br&gt;}&lt;br&gt;/**&lt;br&gt;* 第一個範例類，它與檔案開頭的&lt;br&gt;* 程式內容位於同一個套件中&lt;br&gt;* @package 範例&lt;br&gt;* @subpackage 類別&lt;br&gt;*/&lt;br&gt;class myclass {&lt;br&gt; /**&lt;br&gt; * 一個範例私有變量，可以使用 --parseprivate&lt;br&gt; * 選項&lt;br&gt; * @access private&lt;br&gt; * @var integer|string&lt;br&gt;*/&lt;br&gt; var $firstvar = 6;&lt;br&gt; /**&lt;br&gt; * @link http://www.example.com 範例連結&lt;br&gt; * @see myclass()&lt;br&gt; * @uses 測試，另一個常數&lt;br&gt; * @var 陣列&lt;br&gt;*/&lt;br&gt; var $secondvar =&lt;br&gt; array( array( var $secondvar =&lt;br&gt; array( array( var $secondvar =&lt;br&gt; array( array( var $secondvar =&lt;br&gt; array( array( &lt;br&gt; 'stuff' =>&lt;br&gt; array(&lt;br&gt; 6,&lt;br&gt; 17,&lt;br&gt; 'armadillo'&lt;br&gt; ),&lt;br&gt; testing => anotherconstant&lt;br&gt; );&lt;br&gt; /&my#&*/ >firstvar = 7;&lt;br&gt; }&lt;br&gt; /**&lt;br&gt; * 建構子設定 {@link $firstvar}&lt;br&gt;*/&lt;br&gt; function parentfunc($paramie)&lt;br&gt; {&lt;br&gt; if ($paramie) {&lt;br&gt; return 6;&lt;br&gt; } else {&lt;br&gt; }&lt;br&gt;/**&lt;br&gt; * 基於 $paramie 回傳一個事物&lt;br&gt; * @param boolean $paramie &lt;br&gt; * @return integer|babyclass&lt;br&gt;*/&lt;br&gt;class babyclass extends myclass {&lt;br&gt; /**&lt;br&gt;* @包裝樣本1&lt;br&gt;*/&lt;br&gt; var $secondvar = 42;&lt;br&gt; /**&lt;br&gt; * 生命、宇宙和一切的答案&lt;br&gt; * @var 整數&lt;br&gt;*/&lt;br&gt; var $secondvar = 42;&lt;br&gt; /**&lt;br&gt; * 配置值&lt;br&gt; * @var 陣列&lt;br&gt;*/&lt;br&gt; var $thirdvar;&lt;br&gt; /** &lt;br&gt; * 呼叫父建構函數，然後遞增 {@link $firstvar} &lt;br&gt;*/&lt;br&gt; function babyclass()&lt;br&gt; {&lt;br&gt; parent::myclass();&lt;br&gt; $this->firstvar++;&lt;br&gt; }&lt;br&gt; /**&lt;br&gt; * 這總是回傳一個 myclass &lt;br&gt; * @param 忽略了 $paramie &lt;br&gt; * @return myclass &lt;br&gt;*/&lt;br&gt; function parentfunc($paramie)&lt;br&gt; /**&*/&lt;br&gt; function parentfunc($paramie)&lt;br&gt; &lt;br&gt; myclass;&lt;br&gt; }&lt;br&gt;}&lt;br&gt;?>&lt;br&gt;&lt;br&gt; &lt;br&gt; 以上就介紹了PDP Document程式碼註解規範，包含了require,include,全域變數,注意事項,百度方面的內容，希望對PHP教學有興趣的朋友有幫助。 &lt;br&gt; &lt;br&gt; &lt;br&gt;</cellog></var></samp> </ul> </li></kdb>