基礎級-phpDocumentor

設想一下，你自己設計、書寫的程序，倘若無需他人蔘與，你是否就不需要文檔？
　時隔一年，你還能記清代碼中的細節嗎？一個方法的參數是整型，還是字符串類型？亦或是布爾型？
　　編程作爲一種興趣，我對它報以熱情、投入成本，自然就不希望：我親手書寫的代碼，變成盤根錯節的麻繩，絆倒我自己。畢竟，我們很難追蹤系統的工作方式和編碼目的，對於一個大型項目來說，往往文檔會成爲致命級的存在。

用法

　　在phpDocumentor中，註釋分爲文檔性註釋和非文檔性註釋。前者會被phpDocumentor解析爲文檔內容，後者被忽略，故而，我們只討論文檔性註釋。
　　安裝，PEAR也可以，我是採用官網下載，直接放置於Apache虛擬目錄下，訪問對應網址即可進入Web端；將目錄定位於物理目錄上，也可以運行命令行。
　　PEAR命令-升級或安裝PhpDocumentor：pear upgrade PhpDocumentor；
　　下載了PhpDocumentor包後，PEAR安裝：pear install PhpDocumentor-1.43.tgz；
　　（指南：PhpDocumentor包中INSTALL文件，提供了詳細的說明和疑難解答）
　　使用：依然是代碼行，Web端只需要翻譯器或者英語基礎即可。
-d： 代碼的存放目錄
-t： 文檔的存放目錄
-ti：項目標題
-dn：默認包名
-pp：是否對 私有元素 生成文檔（parseprivate）

phpdoc -d megaquiz/ \
　　　　-t doc/megaquiz/ \
　　　　-ti 'Mega Quiz' \
　　　　-dn 'megaquiz'
        -pp on

格式

/**
* Content...
*/

　　上述格式，在phpDocumentor裏稱爲DocBlock（文檔區），DocBlock是指軟件開發人員編寫的，關於某個關鍵字的幫助信息，使得其他人能夠通過它知道這個關鍵字的具體用途，如何使用。
　　phpDocumentor規定一個DocBlock包含如下信息：
　　（每個部分，空行隔開）
　　　1. 功能簡述區：簡明扼要的描述類、方法、函數的功能。
　　　2. 詳細說明區：說明API的功能、用途、參數、邊界、是否跨系統、注意事項等。
　　　3. 標記Tag：返回值、繼承關係、相關方法等。

　　借用參考資料的代碼：

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

　　如上述。我採用的是Web端測試：Logo同行的就是各種選項，英文基礎即可弄懂，右下角是“Create”創建文檔——前提是你設置完畢。

特殊關鍵字

/** 
* @package command //標記該類所屬的包
* @author Weall.C.Mark //標記作者
* @copyright 2004 Ambridge Technologies Ltd //標記版權信息
* @license http://www.example.com/lic.html Borsetshire Open License //指向許可的URL，以及介紹
* @var string //標記一個屬性
* @return bool執行失敗返回False，成功返回True。
* @see Command::$exe; //在文檔中，對其他內容的引用，並創建超鏈接
* @link http://www.baidu.com/index.php //只包含對元素（Command::execute();）的引用，也用於指向URL
* @user CommandContext //可以在本文檔中創建一個鏈接（User:CommandContext），而在CommandContext類文檔中，將出現新鏈接：Command::execute();
*/

Tips：
- 文件的文檔，文件描述位於文件中第一個DocBlock。許多開源項目要求含有許可公告或指向許可公告的URL。[@license]
- 類的文檔：包含一個摘要、一個可選的描述，以及特殊關鍵字。用於標示一個類，解釋它的用法，增加所屬包、作者、版權等信息。[@package、@author、@copyright]
- 屬性的文檔：PHP的屬性類型是混合的，儘管弱類型語言很方便，但大多數時候，屬性應該是一個特定的數據類型。[@var]
- 方法的文檔：近似類的文檔，多了返回值的描述，因爲PHP的弱類型，返回值需要更詳細的描述。[@return]
- 抽象類、抽象方法的文檔：看起來，添加比代碼內容還多的文檔看起來有點怪異，但抽象類的文檔特別重要，因爲它爲程序員理解如何擴展類提供了方向，當然，理想方式是在安裝程序時刪除註釋（這裏需要運用你的構建工具，不贅述）
- 文檔中的鏈接：關聯相關類、方法、其他元素或外部站點。[@see]

結語

本篇介紹了PhpDocumentor的核心內容，這對團隊協作的意義重大。PhpDocumentor還有更多奇妙的功能，歡迎前往官網瞭解（網址見參考資料）。

參考資料：
《深入PHP：對象、模式與實踐》 - Matt Zandstra
PHP Document 代碼註釋規範 - leonzhang2008
PhpDocumentor官網