phpDocumentor的使用方法

有些phper写的代码在一段时间后可能自己都看不懂自己写的代码是什么，而且还不写注释，给未来读这段代码的人或者自己带来了困扰，这次说一下php中利用代码注释生成文档的一个包，phpDocumentor。
在这里许个愿，希望以后我自己读到的代码都能有一些良好的注释

简单介绍

phpDocumentor（phpDoc）是一个记录文档的程序，会自动帮你根据项目中所有文件的文档块然后生成文档

安装方式

官方推荐安装方式为docker安装
第二种就是手动下载phar包
第三种就是使用phive，我是使用这种方式安装的，需要注意，使用这种方式安装的时候，默认会下载最新的版本，可能和你的php环境不符…比如我的php版本就是7.3的，所以你就需要去官网上面找支持你php版本的包，比如我7.3的版本需要下载做了向下兼容7.3版本的phpDocumentor@v3.2.1
另外，官方并不推荐composer的方式，虽然有这种方式

这里要说明一下，phar包可以在win10中的powershell中运行也可以在gitbash中运行，想要全局安装的话，只需要把扩展名删掉，然后在系统的环境变量中添加这个文件的路径，就可以在你需要使用phpDocumentor生成文档的项目根路径中使用这个命令了

命令参数

-d 指定要记录的项目的一个或多个目录。默认会在你执行命令的目录内的文件
-f 指定项目中要记录的一个或多个特定文件
-t 指定文档的写入目录，默认会在你执行命令的目录下生成一个.phpdoc的文件夹
-i 忽略某个文件或者目录支持通配符的方式，例如 -i “./*/*test.php”
–title 浏览器的标题，可以写你的项目名称
其余的命令看起来没有什么实际的东西，你可以自己用-h去查看

文档块

整个程序做的所有内容都是研究注释
所以文档块就是注释的规则

文档块区分三个部分
标题->描述->标签

标题：简单说一下这个文档块负责的是什么
描述：详细说一下具体想干啥，有什么作用，给我感觉和上面差不多…扩展会识别每一部分在 [ . ]后换行结束,或者在有一行空白注释行结束，所以我的建议是，写完标题部分就给一行空注释，方便阅读，也少写了一个[ . ],对吧！

你可以用利用标签简单写一点注释，每一个部分其实都不是必须的
大概就是类似于这样的

/**
  * 我是一个标题
  *
  * 元素描述
  * @param string $a  [参数描述]
  * @return void [返回值描述]
*/

可以在下面每一个结构体之前标记你的文档块
Function | Constant | Class | Interface | Trait
还有page(就是整个文件)的开头,比如 [ <?php ] 的下一行

标签

这里只说明我觉着有用的标签，其余标签不是很好用

标签	描述
@param [类型] [变量名]	声明function需要传入的参数和类型
@return [类型] [描述]	声明function的返回类型和描述
@throws [异常类型] [描述]	用于提示可能会抛出的异常类型和文本描述
@property | @property-read | @property-write [类型] [属性名]	声明类属性[可读写 | 只读 | 只写]
@package [包名]	声明当前文档块下的元素包名，[ \ ] | [ _ ]会解析成包分隔符
@deprecated <版本> [描述]	此标签用来说明当前文档块下的元素已经弃用的版本和原因
@link [URL] [描述]	此标签用来写入一个url链接，这个标签有行内写法像这样 : {@link [URL] [描述]}
@see [文档中存在的元素 | URL]	用于链接到文档内的任何元素，或者URI
@uses [文档中存在的元素] [描述]	看起来和see差不多，不同的是这个标签会在对应的元素中自动生成反标签
@todo [描述]	提示可能将要开发的文件或者function
@method [return] [方法名(参数)] [描述]	用于声明使用魔术方法来实现的一些非显示存在方法
@ignore	此标签用来告诉phpDocumentor需要忽略记录的元素

其余标签可以自己去官方查看，这里就不介绍了

类型

这里说的是上面标签里的类型的解释
第一 php原有的类型
int、string、array、float、bool、object、callable、iterable、resource、null

第二 可以是类名，也可以是类的别名，以及某命名空间下的类名比如 \Test

第三 还可以是在phpDoc标准的特殊关键字或者伪类型，比如 falsofixed 等
假如你use了一个类并且起了别名的话如 use \Test as Test1; 那么类型也可以是Test1

还可以是伪类型，比如：

• mixed 可以是任何类型
• void 无任何类型
• false|true 显示的bool类型
• self 自身
• static 静态如果有继承，将表示子类
• $this 通常表示对象实例

另外可以写成string[ ] | callable[ ] 等等这种，表示接收的是字符串类型数组 | 回调函数的数组等
想使用多种类型时也可以通过管道符[ | ]来表示，例如bool | string 这种方式