phpdocumentor详解

为什么要使用文档

喜欢和厌恶文档的程序员都很多。当你迫于项目最后期限的压力以及经理和客户盯着你的任务时，首先被放弃的通常是文档。这时候我们只想着早点完成代码。当然我们可以尽可能编写优雅的代码，但是对于一个正在飞速发展的项目来说，文档就像在浪费时间。当然，每个人都赞同应该有一份良好的文档，只是没有人愿意降低生产来编写文档。

假设有一个很大的项目，其代码库非常庞大，它由聪明的人们编写的优秀代码组成。团队成员已经为这个项目工作了3年以上，他们彼此非常熟悉，也完全理解代码。当然项目文档也就比较少。在每个人的头脑里都有一副项目的大局图。后来队伍增加了新成员。原来的成员向新人很好的介绍了这个复杂系统结构，接着就让他们开始工作。这时候代码不写文档的问题就暴露了：如果有文档，新人可能一两个星期就能熟悉代码并开始工作；如课没有文档，可能需要几个月才能读懂代码。假如对于一个没有文档的类，新的程序员不得不跟踪每一个方法的参数，追踪每一个被引用的全局变量，检查继承体系中所有的方法。如果有一份文档，你就可以从中解脱出来。但如果把文档当作代码一样看待，那么写文档并不困难。

如果把文档当作代码本身的一部分增加到源代码中，写文档的过程就变得很容易，然后你可以运行工具将注释提取出来放到美观的网页中去。

上面提到的工具就是本次要跟大家分享的phpDocumentor,phpDocumentor由一个名为javaDoc的java工具移植而来。这两个工具都能从源代码中提取特定的注释，利用从程序员的注释和源代码中得到代码结构来构建复杂的API文档。

安装

这里就只介绍用composer安装phpDocumentor

$composer require "phpdocumentor/phpdocumentor:2.*"

完成之后，你在当前目录中可以看到一个vendor的目录

$ lltotal 4072-rw-r--r--@   1 dingjiacai  staff  1941886  6  2 17:16 IMG_2447.jpg-rw-r--r--    1 dingjiacai  staff      134  6  8 10:44 composer.json-rw-r--r--    1 dingjiacai  staff   123647  6  8 10:44 composer.lockdrwxr-xr-x   27 dingjiacai  staff      918  6  8 10:44 vendordrwxr-xr-x    4 dingjiacai  staff      136  5 24 11:14 wwwdrwxr-xr-x   13 dingjiacai  staff      442 12  5  2016 设计模式$ 

安装完毕

DocBlock

如果要得到一份价值很高的文档，那接下来就得学习一下DocBlock。当我们完善的注释后，重先生成的文档给我们的开发带来怎么样的效率？亲自尝试了就知道。

DocBlock注释有特定的格式，以便被文档程序识别。它们采用标准的多行注释格式

／**  * 我的DocBlock注释  *／

类，属性，方法注释

为了方便大家理解，直接给出列子

Command.php

<?phpnamespace App;/** * 定义命令的核心功能 * @version v1.0 * @copyright Steve * [2017-06-13] * @link http://www.baidu.com * */abstract class Command{    /**     *  执行命令     *  @param object $context 环境     *  @return bool 执行成功返回true，反之false     *  @uses CommandContext      */    abstract function exec(CommandContext $context);}

备注：@uses区别于@see，@link，它可以实现双向链接，@uses CommandContext可以在Command的exec方法中生成一个链接到CommandContext，而在CommandContext类中，将出现一个新链接：Used by:Command::exec()

CommandContext.php

<?phpnamespace App;/** * @see Command::exec() */class CommandContext{    /**     * 应用名称     * @var string     */    public $applicationName;    /**     * 封装好的健值对     * @var array     */    public $params = array();    /**     * 出错信息     * @var string     */    private $error = "";}

生成文档

phpDocumentor作为命令好工具运行，也可以通过web GUI（web图形用户界面）来访问。我们将重点讨论命令行方式，因为它更易于将文档的更新操作嵌入到编译工具或者shell脚本。调用phpDocumentor的命令是phpdoc，运行该命令时还需要提高一系列参数一生成文档。

假如我们正对donghu这个项目生成文档，并把文档保存到donghu_doc这个目录中

$./vendor/bin/phpdoc -d ~/DocBlock/ -t ./DocBlock_doc/

备注：关于phpdoc指令的参数，这里就不一一介绍，通过./vendor/bin/phpdoc -h自己查看

文档效果

总结

本次介绍的phpDocumentor的核心特性，探讨了DocBlock注释语法以及可以与它一起使用的标签，讨论了如何为类，属性和方法添加文档，并且提供了足够的标签来转化文档，这对于改善团队协作意义重大。要想了解更多phpDocumentor功能，你可以通过官方站点https://phpdoc.org/了解。