php-doc
老的版本是phpdoc，从1.3.0开始，更名为phpDocumentor
PHP Documentor是PEAR下面的一个模块，用来生成文档。PHP Documentor扫描指定目录下面的php源代码，扫描其中的关键字，截取需要分析的注释，然后分析注释中的专用的tag，生成html文件，接着根据已经分析完的类和模块的信息，建立相应的索引，生成html文件
如果没有安装http://pear.php.net/go-pear，文件另存为一下。命令行下php go-pear.php，就可以安装了。 我是用yum安装的php，安装的时候，pear已经安装了。pear安装好后，我可以通过pear install phpDocumentor来安装phpdoc
$curl -o go-pear.php http://pear.php.net/go-pear
$php go-pear.php
Sorry! Your PHP version is too new (7.0.15) for this go-pear.
Instead use http://pear.php.net/go-pear.phar for a more stable and current
version of go-pear, more suited to your PHP version.
$curl -o go-pear.phar http://pear.php.net/go-pear.phar
$php go-pear.phar
$vi ~/.bashrc
export PATH=”/Users/didi/pear/bin:$PATH”
$pear help
$pear install phpDocumentor
$phpdoc -h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
标记 用途 描述
@abstract 抽象类的变量和方法
@access public, private or protected 文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author 张三 <zhangsan@163.com> 文档作者
@copyright 名称 时间 文档版权信息
@deprecated version 文档中被废除的方法
@deprec 同 @deprecated
@example /path/to/example 文档的外部保存的示例文件的位置。
@exception 文档中方法抛出的异常，也可参照 @throws.
@global 类型：$globalvarname 文档中的全局变量及有关的方法和函数
@ignore 忽略文档中指定的关键字
@internal 开发团队内部信息
@link URL 类似于license 但还可以通过link找到文档中的更多个详细的信息
@name 变量别名 为某个变量指定别名
@magic phpdoc.de compatibility
@package 封装包的名称 一组相关类、函数封装的包名称
@param 如 [$username] 用户名 变量含义注释
@return 如 返回bool 函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see 如 Class Login（） 文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since version 记录什么时候对文档的哪些部分进行了更改
@static 记录静态类、方法
@staticvar 在类、函数中使用的静态变量
@subpackage 子版本
@throws 某一方法抛出的异常
@todo 表示文件未完成或者要完善的地方
@var type 文档中的变量及其类型
@version 文档、类、函数的版本信息
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的规范化注释：
- 生成文档：
规范的注释写好了，下面要真正生成文档了：
举例：
phpdoc -d ./a -t ./b -dn abc -dc def -ti xyz -o HTML:Smarty:PHP
上面的意思是：为./a下的php文件生成文档，存放在./b目录下，包名是abc，目录名是def，标题是xyz，以HTML:Smarty:PHP为模板。
