PHP文檔生成器（PHPDoc）的基本用法
PHPDoc概述
PHPDoc是一種注釋PHP代碼的正式標准，一般是通過外部文檔生成器phpDocumentor生成API文檔。同事支持面向過程和面向對象的代碼風格，而且很多高級IDE如PHPStorm對其有很好的支持。靈活使用PHPDoc生成API文檔可以有效提高開發效率，本文主要是記錄PHPDoc的基本用法。
安裝
PHPDoc官方提供三種安裝方式，分別是通過pear、composer和phar進行安裝。Linux通過pear安裝phpdoc比較簡單，只需按照官方引導即可。composer主要針對項目，需要注意的是composer安裝phpdoc會引入很多依賴包。phar方式需要下載phpDocumentor外部文檔，然后在終端通過php-cli進行調用即可。本文采用了第三種方法，這種方法可以兼容各操作系統，並且不需要安裝額外軟件。
PHPDoc注釋規范
頁面級別的注釋
一般來說，頁面級的文檔塊就是文件中出現的第一個文檔塊，推薦使用@package標簽對文件路徑進行標注。
代碼級別的注釋
代碼級別主要指類、變量和方法的注釋塊，其中方法的參數值和返回值注釋與PHP的數據類型基本相同。需要注意PHPDoc不支持對單行注釋的解析，所以需要使用代碼塊。
生成API文檔
php phpDocumentor.phar -d Pro/ -t docs/api
-d后面跟文件夾路徑，如果是單個文件，可以用-f。-t表示目標target，后面跟API文檔生成的文件夾。如果需要指定模板，可以在代碼后面追加--template。
php phpDocumentor.phar -d Pro/ -t docs/api --template="clean"
可以通過template:list查看所支持的內置模板
php phpDocumentor.phar template:list
可以直接在template后面接自定義模板
php phpDocumentor.phar -d Pro/ -t docs/api --template="data/template/my_template"
額外軟件
- 如果需要查看類的圖表，需要安裝Graphviz。以ubuntu為例
sudo apt-get install graphviz