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

Posted 承丶山

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了PHPDocumentor2.8.5 安装,使用及快速上手相关的知识,希望对你有一定的参考价值。

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下面的所有无标记注释都会被显示出来。




























































































































以上是关于PHPDocumentor2.8.5 安装,使用及快速上手的主要内容,如果未能解决你的问题,请参考以下文章

微擎安装使用及插件模块安装

大数据DataX:DataX安装及使用

Cisco的安装汉化及基础使用详情

Flume的安装及使用

ovirt安装及使用

Linuxbrew安装及使用介绍