PHP文檔生成器（PHPDoc）的基本用法

[TOC]

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