phpDoc使用入門

phpDoc使用入門

1.下載

在 http://sourceforge.net/projects/phpdocu/files/下載phpDoc，我的版本是1.4.3

2.使用

解壓出來後，終端：phpdoc -h   可以查看所有的指令，選幾個重要的：

-d     源php檔案的路徑

-t      產生文檔後文檔的存放路徑（最好為其單獨建立一個檔案夾）

-dn   包的名字（預設為default，最好改成項目的名字）

-dc   目錄的名字（預設為default，最好改成項目的名字）

-ti     文檔標題  這是首頁上的大標題

-o     產生的文檔的模板格式，這個應該有很多種可以選擇，不過我只選擇：HTML:Smarty:PHP（感覺比較美觀）

3.

注釋規則（其實和大多數的文檔產生工具是差不多的，如javadoc，doxygen，jsdoc等）

下面的部分整理自網路：

注意：phpDoc和其他的自動化文檔產生工具不一樣，不可以在注釋中添加html代碼！

1.

每個php檔案開頭：

/** * Common base class of all phpdoc classes （簡述，用在索引列表中，應盡量只佔一行） * * As a kind of common base class PhpdocObject holds * configuration values (e.g. error handling) and debugging * methods (e.g. introspection()). It does not have a constructor, * so you can always inheritig Phpdoc classes from this * class without any trouble. （詳細的功能描述，可以多行） * * @author   Ulf Wendel  * @version  $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $ * @package  PHPDoc （文檔標記）（你可以將不同的模組放在不同的package裡，產生文檔的時候會自 * 動產生一個包列表，可以在文檔的左上方選擇不同的包查看不同的模組文檔） */

下面是一段phpDoc的正常化注釋：

4. 產生文檔：

規範的注釋寫好了，下面要真正產生文檔了：

舉例：

phpdoc -d ./a -t ./b -dn abc -dc def -ti xyz -o HTML:Smarty:PHP

上面的意思是：為./a下的php檔案產生文檔，存放在./b目錄下，包名是abc，目錄名是def，標題是xyz，以HTML:Smarty:PHP為模板。

5.遇到的問題：

產生文檔的時候可能由於時區沒有設定，會在產生後的文檔中出現如下warning：

Warning: strftime(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any
of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'Asia/Chongqing' for 'CST/8.0/no DST' instead in /home/hutao/phpDocumentor/Files/PhpDocumentor-1.4.3/PhpDocumentor-1.4.3/phpDocumentor/Smarty-2.6.0/libs/Smarty_Compiler.class.php
on line 370

解決辦法：

按warning提示開啟Smarty_Compiler.class.php檔案，然後在第二行（第一行是<?php）加入：

date_default_timezone_set('Asia/Shanghai');    //'Asia/Shanghai'   亞洲/上海

上面表示手動選擇一個時區

然後再運行第四步的命令就可以啦～～～

完成！