PHPDocumentor2.8.5 安装，使用及快速上手

Posted 2020-09-01 承丶山

phpDocumentor当前版本是phpDocumentor-2.8.5.tgz

关于PHPDocumentor有什么用，还有其历史，我就不介绍了，直接进入正题。
老版本的叫PHPDoc，从1.0开始，2017/2月的最新版本是：1.4.4（PHPDoc已经停止发布了直接新版本走起吧，新版本支持更好）
新版本叫PHPDocumentor，从2.0本版本开始，2017/2月的最新版本是：2.8.5
2.0的官方网站：https://phpdoc.org

一 安装phpDocumentor
安装phpDocumentor有三种方法：
a.使用pear
加入phpdoc的频道
$ pear channel-discover pear.phpdoc.org

安装phpdoc
$ pear install phpdoc/phpDocumentor

这种方法受限于pear，windows下能正常下载，但是会无法解压安装包。
报错：ERROR: unable to unpack c:/*****

b.直接使用phpDocumentor.phar文件执行phpDoc接口文档生成
下载phpDocumentor.phar
http://www.phpdoc.org/phpDocumentor.phar.

下载后进入到phpDocumentor.phar文件所在目录，直接执行接口文档生成命令，
即可以用php phpDocumentor.phar后面加上下面第二部分的参数，（个人理解是免安装）
直接使用PHPDocumentor生成接口文档。
php phpDocumentor.phar -d . -t docs/api

c.使用Composer
Composer官网https://getcomposer.org

安装Composer
php -r "copy(‘https://getcomposer.org/installer‘, ‘composer-setup.php‘);"
php -r "if (hash_file(‘SHA384‘, ‘composer-setup.php‘) === ‘55d6ead61b29c7bdee5cccfb50076874187bd9f21f65d8991d46ec5cc90518f447387fb9f76ebae1fbbacf329e583e30‘) { echo ‘Installer verified‘; } else { echo ‘Installer corrupt‘; unlink(‘composer-setup.php‘); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink(‘composer-setup.php‘);"

指定配置项安装
指定安装路径
php composer-setup.php --install-dir=bin

指定文件名
php composer-setup.php --filename=composer

指定版本
php composer-setup.php --version=1.0.0-alpha8

安装phpdoc
$ composer require "phpdocumentor/phpdocumentor:2.*"

小结：
三种方法都试下来：
b方法免安装最靠谱，但是使用的时候要进入到phpDocumentor.phar文件所在目录（或者干脆把此文件放到环境变量目录下），然后把下文中的phpdoc命令换成php phpDocumentor.phar;
a方法能下载，但是windows下会报ERROR: unable to unpack c:/*****的安装错误；
c方法莫名其妙，明明安装成功了，但是使用phpdoc命令的时候，告诉我该命令不存在。。。难道是windows下环境变量的问题？以后再研究了。

二 设置，查询，生成模板
a.查看模板列表
能查询出当前有哪些可用模板
$ phpdoc template:list

b.按指定模板生成文档
$ phpdoc -d "./src" -t "./docs/api" --template="checkstyle"
一次生成不同模板的文档
$ phpdoc -d "./src" -t "./docs/api" --template="checkstyle,clean"
生成自定义模板的文件
$ phpdoc -d "./src" -t "./docs/api" --template="data/templates/my_template"

c.开始生成接口文档
一共有三种写法，作用都一样，如下：
$ phpdoc -d|-f <PATH> -t <PATH> [parameters]
$ phpdoc run -d|-f <PATH> -t <PATH> [parameters]
$ phpdoc project:run -d|-f <PATH> -t <PATH> [parameters]

-d后面跟着需要编译的接口目录
-f后面跟着需要编译的接口文件
-d和-f二选一
-t是指把接口文档生成到什么位置
[parameters]是后面添加的其他参数
–encoding 编码方式
–title[=”...”]文档的标题
–force忽略异常继续执行
--template=""选择需要编译的模板

还有很多不常用，详细请看官方文档:
https://phpdoc.org/docs/latest/references/commands/project_run.html#usage

例子：
phpdoc(或php phpDocumentor.phar) -d "E:\PHPDoc\Controller" -t "E:\PHPDoc" --template="responsive-twig"

*****注意：一定要用双引号*****

小结：
生成的文档文件直接用浏览器打开；
或者
把目标目录（上例中-t后面的E:\PHPDoc）内的新生成文件拷贝到服务器目录下，访问服务器打开。

三 注释填写规范

标记名字 标记使用范围    标记描述
@api methods 声明元素适合第三方消费。
@ahthor any 文档的相关元素的作者。
@category file,class 组合一系列包。
@copyright any 记录相关元素的版权信息。
@deprecated any 表明相关的元素是不可以在未来的版本中删除。
@example any 显示指定的示例文件的代码，或可选地，只是其中的一部分。
@filesource file 包含用于输出的当前文件的源。
@global variable 通知一个全局变量或使用phpDocumentor。
@ignore any 告诉phpDocumentor，伴生元素并不包含在文档中。
@internal any 表示关联元素是此应用程序或库的内部，并在默认情况下将其隐藏。
@license any 指示关联元素适用于哪个许可证。
@link any 表示关联元素与网站页之间的关系。
@method class 允许一个类知道这“神奇”的方法调用。
@package file,class 将相关的元素为一个逻辑分组或细分。
@param method,fucntion 记录函数或方法的单个参数。
@property class 允许类知道哪些“魔法”属性存在。
@property-read class 允许类知道哪些“魔法”属性是只读的。
@property-writer class 允许类知道哪些“魔术”属性是目前只写。
@return method,function 记录函数或方法的返回值。
@see any 指示从关联元素到网站或其他元素的引用。
@since any 指示关联元素在哪个版本可用。
@source any,except file 显示关联元素的源代码。
@subpackage file,class 将相关的元素为一个逻辑分组或细分。
@throws method,function 指示关联的元素是否会引发特定类型的异常。
@todo any 指示是否应在关联元素上执行任何开发活动。
@uses any 表示引用（和从）单个关联元素。
@var properties
@version any 表示结构元素的当前版本。

小结：
最常用的就是@return ，把想显示的注释内容放到这个标记下面，
那么@return下面的所有无标记注释都会被显示出来。