为什么要使用文档
喜欢和厌恶文档的程序员都很多。当你迫于项目最后期限的压力以及经理和客户盯着你的任务时,首先被放弃的通常是文档。这时候我们只想着早点完成代码。当然我们可以尽可能编写优雅的代码,但是对于一个正在飞速发展的项目来说,文档就像在浪费时间。当然,每个人都赞同应该有一份良好的文档,只是没有人愿意降低生产来编写文档。
假设有一个很大的项目,其代码库非常庞大,它由聪明的人们编写的优秀代码组成。团队成员已经为这个项目工作了3年以上,他们彼此非常熟悉,也完全理解代码。当然项目文档也就比较少。在每个人的头脑里都有一副项目的大局图。后来队伍增加了新成员。原来的成员向新人很好的介绍了这个复杂系统结构,接着就让他们开始工作。这时候代码不写文档的问题就暴露了:如果有文档,新人可能一两个星期就能熟悉代码并开始工作;如课没有文档,可能需要几个月才能读懂代码。假如对于一个没有文档的类,新的程序员不得不跟踪每一个方法的参数,追踪每一个被引用的全局变量,检查继承体系中所有的方法。如果有一份文档,你就可以从中解脱出来。但如果把文档当作代码一样看待,那么写文档并不困难。
如果把文档当作代码本身的一部分增加到源代码中,写文档的过程就变得很容易,然后你可以运行工具将注释提取出来放到美观的网页中去。
上面提到的工具就是本次要跟大家分享的phpDocumentor,phpDocumentor由一个名为javaDoc的java工具移植而来。这两个工具都能从源代码中提取特定的注释,利用从程序员的注释和源代码中得到代码结构来构建复杂的API文档。
安装
这里就只介绍用composer安装phpDocumentor
$composer require "phpdocumentor/phpdocumentor:2.*"
完成之后,你在当前目录中可以看到一个vendor的目录
$ ll
total 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.lock
drwxr-xr-x 27 dingjiacai staff 918 6 8 10:44 vendor
drwxr-xr-x 4 dingjiacai staff 136 5 24 11:14 www
drwxr-xr-x 13 dingjiacai staff 442 12 5 2016 设计模式
$
安装完毕
DocBlock
如果要得到一份价值很高的文档,那接下来就得学习一下DocBlock。当我们完善的注释后,重先生成的文档给我们的开发带来怎么样的效率?亲自尝试了就知道。
DocBlock注释有特定的格式,以便被文档程序识别。它们采用标准的多行注释格式
/**
* 我的DocBlock注释
*/
类,属性,方法注释
为了方便大家理解,直接给出列子
Command.php
<?php
namespace 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
<?php
namespace 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/了解。