概况

这篇文章的目标是了解 PHPDoc 的使用，文末附上了两个开源项目作为参考。关于 PHPDoc 的安装办法可以查看上一篇文章。

DocBlocks 以注释的形式出现，但又不仅仅是注释。它是一份行内的文档，可以让你回想起这一块代码是用来干什么的，phpdoc也根据它来生成文档。

DocBlock使用范围包括

• 函数（function）
• 常量
• 类
• 接口
• trait
• 类内常量
• 类属性
• 类方法(method)
• include require

一个标准的 DocBlock 像这样子：

 <?php
 /**
  * 这是关于这个function的总结。
  *
  * 这是关于function的 *详细描述* 。
  * 可以使用markdown样式
  *
  * @param 这是输入标签。
  *    下面的return是返回值标签。
  *
  * @return void
  */
  function myFunction($myArgument)
  {
  }

运行

$ phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder

运行phpdoc时，需要指定扫描的文件夹或者文件，或者事先在配置文件 phpdoc.xml 中声明。 如果没有指定导出文件夹，则默认导出到当前目录下的output。

配置文件 phpdoc.xml 一般放在项目目录下。全局配置文件 phpdoc.dist.xml 在 phpdoc 的安装目录下，也可以修改。

模板

模板文件在 PHPDoc 的安装目录的 data\templates 目录下。

$ 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" // 使用自定义模板

我们可以使用 XSL 或者 Twig 模版引擎来自定义模板。phpDoc 提供了很多便利的方法。希望自定义折腾的可以去试试。默认的模板clean我并不喜欢，我选了颜值最高的responsive模板。样式如下：

 phpdoc --template="responsive" -d ./app -t ./docs

与IntelliJ IDEA结合

大部分人写代码还是需要IDE的。可以帮忙做诸如自动补全、预编译报警等等很多事情，减少问题，加快开发进度。我常用的是 JetBrains 厂的 IntelliJ Idea。 PHPDoc 和 IDEA 的结合还是蛮可以的。从 PHPDoc 的官网上就可以看出来, JeyBrains 还是他们的赞助商。

一些简单的使用方法可以在 Idea 官网找到。最常用的就是在方法或者类名之前输入 /** 后按回车键，自动将常用的 Tag 给写好了。

除了写代码时的便利，导出也可以借由 IDEA 完成。

菜单栏 Run -> Edit Configurations,增加php脚本配置。在 File 栏目填写 phpdoc 的路径，例如我的 C:\my_pp\php\php-5.5.30-nts-Win32-VC11-x64\phpdoc,在 Arguments 栏目填写运行变量，例如我的 --template="responsive" -d "C:\Workspace\wechat.kelu.org\app" -t "C:\Workspace\wechat.kelu.org\docs"

Docblocks详解

Docblocks 使用 Tag 的形式来标记。

实例参考

下面参考一下两个开源项目的 DocBlocks。

1. October

    /**
     * Administrator user model
     *
     * @package october\backend
     * @author Alexey Bobkov, Samuel Georges
     */
    class User extends UserBase
    {
        /**
         * @var string The database table used by the model.
         */
        protected $table = 'backend_users';
   
        /**
         * Validation rules
         */
        public $rules = [
            'email' => 'required|between:6,255|email|unique:backend_users',
            'login' => 'required|between:2,255|unique:backend_users',
            'password' => 'required:create|between:4,255|confirmed',
            'password_confirmation' => 'required_with:password|between:4,255'
        ];
   
        /**
         * Relations
         */
        public $belongsToMany = [
            'groups' => ['Backend\Models\UserGroup', 'table' => 'backend_users_groups']
        ];
   
        public $attachOne = [
            'avatar' => ['System\Models\File']
        ];
   
        /**
         * Purge attributes from data set.
         */
        protected $purgeable = ['password_confirmation', 'send_invite'];
   
        /**
         * @var string Login attribute
         */
        public static $loginAttribute = 'login';
   
        /**
         * @return string Returns the user's full name.
         */
        public function getFullNameAttribute()
        {
            return trim($this->first_name . ' ' . $this->last_name);
        }
   
        /**
         * Gets a code for when the user is persisted to a cookie or session which identifies the user.
         * @return string
         */
        public function getPersistCode()
        {
            // Option A: @todo config
            // return parent::getPersistCode();
   
            // Option B:
            if (!$this->persist_code) {
                return parent::getPersistCode();
            }
   
            return $this->persist_code;
        }
        ......
    }
   

2. BootstrapCMS

   这个项目的开发者也是 laravel 开发组成员。

    /*
     * This file is part of Bootstrap CMS.
     *
     * (c) Graham Campbell <graham@alt-three.com>
     *
     * For the full copyright and license information, please view the LICENSE
     * file that was distributed with this source code.
     */
   
    namespace GrahamCampbell\BootstrapCMS\Models\Relations;
   
    /**
     * This is the has many comments trait.
     *
     * @author Graham Campbell <graham@alt-three.com>
     */
    trait HasManyCommentsTrait
    {
        /**
         * Get the comment relation.
         *
         * @return \Illuminate\Database\Eloquent\Relations\HasOneOrMany
         */
        public function comments()
        {
            return $this->hasMany('GrahamCampbell\BootstrapCMS\Models\Comment');
        }
   
        /**
         * Delete all comments.
         *
         * @return void
         */
        public function deleteComments()
        {
            foreach ($this->comments()->get(['id']) as $comment) {
                $comment->delete();
            }
        }
    }
   

参考资料

• PHPDoc 官网
• PHP的Annotations