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'   亚洲/上海

上面表示手动选择一个时区

然后再运行第四步的命令就可以啦～～～

完成！