[TOC] * * * * * Phpdocumentor使用心得 ### 一、非集成環境 #### 1. 依賴pear安裝： a)安裝pear：下載pearhttp://pear.php.net/go-pear.phar； 將go-pear.phar放到PHP目錄下 執行安裝命令： ~~~ php go-pear.phar ~~~ 下面會執行, 輸入system 然后一路回車,安裝完畢 #### 2. 手動安裝： （此安裝方式可能會涉及smater模板路徑問題） a)下載最新版的phpdocumentor解壓即可 官網地址http://phpdoc.org； ### 二、集成環境 #### 1、依賴pear安裝： ①：查看是否已經安裝pear 方式：打開dos窗口進入php安裝目錄下輸入：`pear` 如果沒有安裝則安裝，方式如上。 ②：查看pear目錄中是否存在phpdocumentor本地包：`pear list`  ③：執行安裝就OK（沒有的話他首先會自動下載，下載之后需要解壓到php/pear下） 進入dos的php目錄，輸入`pear install -a PhpDocumentor`。 如果想使用web接口，則必須首先改變一個配置，在下載的phpdocumentor里面找到`phpdoc.bat`進行如果下編輯 讓`phpCLi=php.exe`這個路徑  ④：可以在dos窗口phpdocumentor目錄下輸入命令生成自己所需要的文檔。 #### 2、手動安裝： b)下載最新版的phpdocumentor解壓即可 官網地址`http://phpdoc.org`； ### 三、生成文檔相關問題 #### 1. 怎樣使用PhpDocumentor生成文檔 a. 命令行方式 在phpDocumentor所在目錄下，輸入`Php -h` 會得到一個詳細的參數表，其中幾個重要的參數如下： -f 要進行分析的文件名，多個文件用逗號隔開 -d 要分析的目錄，多個目錄用逗號分割 -t 生成的文檔的存放路徑 -o 輸出的文檔格式，結構為輸出格式：轉換器名：模板目錄。 例如：`phpdoc -o HTML:frames:earthli -f test.php -t docs` b. Web界面生成 在新的phpdoc中，除了在命令行下生成文檔外，還可以在客戶端瀏覽器上操作生成文檔，具體方法是先把PhpDocumentor的內容放在apache目錄下使得通過瀏覽器可以訪問到，訪問后顯示如下的界面： 點擊files按鈕，選擇要處理的php文件或文件夾，還可以通過該指定該界面下的`Files to ignore`來忽略對某些文件的處理。 然后點擊`output按鈕`來選擇生成文檔的存放路徑和格式. 最后點擊`create`，phpdocumentor就會自動開始生成文檔了，最下方會顯示生成的進度及狀態，如果成功，會顯示 ~~~ Total Documentation Time: 1 seconds done Operation Completed!! ~~~ 然后，我們就可以通過查看生成的文檔了，如果是pdf格式的，名字默認為documentation.pdf。 #### 2. 中文亂碼解決方法 如果注釋是中文的，需把`PhpDocumentor/phpDocumentor/Converters/*`中相應模板的語言標簽執行`iso-8859-1`到`utf-8`的替換，否則生成出來是亂碼。 #### 3. 給php代碼添加規范的注釋 PHPDocument是從你的源代碼的注釋中生成文檔，因此在給你的程序做注釋的過程，也就是你編制文檔的過程。從這一點上講，PHPdoc促使你要養成良好的編程習慣，盡量使用規范，清晰文字為你的程序做注釋，同時多多少少也避免了事后編制文檔和文檔的更新不同步的一些問題。在phpdocumentor中，注釋分為文檔性注釋和非文檔性注釋。所謂文檔性注釋，是那些放在特定關鍵字前面的多行注釋，特定關鍵字是指能夠被phpdoc分析的關鍵字，例如class，var等，具體的可參加附錄一。那些沒有在關鍵字前面或者不規范的注釋就稱作非文檔性注釋，這些注釋將不會被phpdoc所分析，也不會出現在你產生的api文當中。 ##### 如何書寫文檔性注釋: 所有的文檔性注釋都是由`/**`開始的一個多行注釋，在phpDocumentor里稱為`DocBlock`,`DocBlock`是指軟件開發人員編寫的關于某個關鍵字的幫助信息，使得其他人能夠通過它知道這個關鍵字的具體用途，如何使用。PhpDocumentor規定一個DocBlock包含如下信息： 1. 功能簡述區 文檔性注釋的第一行是功能描述區，正文一般是簡明扼要地說明這個類，方法或者函數的功能，功能簡述的正文在生成的文檔中將顯示在索引區。功能描述區的內容可以通過一個空行或者". "來結束。 2. 詳細說明區 在功能描述區后是一個空行，接著是詳細說明區，這部分主要是詳細說明你的API的功能、用途、如果可能也可以有用法舉例等等。在這部分，你應該著重闡明你的API函數或者方法的通常的用途、用法，并且指明是否是跨平臺的（如果涉及到），對于和平臺相關的信息，你要和那些通用的信息區別對待。通常的做法是另起一行，然后寫出在某個特定平臺上的注意事項或者是特別的信息，這些信息應該足夠，以便你的讀者能夠編寫相應的測試信息，比如邊界條件，參數范圍，斷點等等。 3. 標記tag 之后同樣是一個空白行，然后是文檔的標記tag，指明一些技術上的信息，主要是調用參數類型、返回值極其類型、繼承關系、相關方法/函數等等。 ##### 注釋用例 下面是一個文檔注釋的例子 ~~~ /** * 函數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 使用范圍：class，function，var，define，module，use 指明作者 ###### @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 指明在此函數中引用的全局變量 ###### @ignore 用于在文檔中忽略指定的關鍵字 ###### @license 相當于html標簽中的,首先是URL，接著是要顯示的內容 例如百度 可以寫作@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. 總結 編寫文檔是一項乏味卻不得不做的工作，而編寫API級的文檔更是意味著大量的重復勞動和難以保持的一致性。這里我們要推薦給大家的，是支持php5語法分析的文檔工具--phpDocumentor。 phpDocumentor是一個非常強大的文檔自動生成工具，利用它可以幫助我們編寫規范的注釋，生成易于理解，結構清晰的文檔，對我們的代碼升級、維護、移交等都有非常大的幫助。 使用`phpDocumentor`不僅可以自動從代碼中提取出函數和方法定義，還可以自動處理各個class之間的關系，并據此生成class tree。你還可以選擇將文檔生成html、chm或者pdf。 有了phpDocumentor，文檔工作變得輕松了很多。關于`phpDocumentor`更為詳細的說明，可以到它的官方網站：`http://manual.phpdoc.org/`查閱。 作者：久度 鏈接：https://www.jianshu.com/p/0a51d9ddd7b0 來源：簡書 著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請注明出處。