PHPDoc 入门

概况

这篇文章的目标是了解 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 的形式来标记。

标记 用途 描述
@abstract   抽象类的变量和方法
@access public, private or protected 文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author 张三 zhangsan@163.com 文档作者
@copyright 名称 时间 文档版权信息
@deprecated version 文档中被废除的方法
@deprec   同 @deprecated
@example /path/to/example 文档的外部保存的示例文件的位置。
@exception   文档中方法抛出的异常,也可参照 @throws.
@global 类型:$globalvarname 文档中的全局变量及有关的方法和函数
@ignore   忽略文档中指定的关键字
@internal   开发团队内部信息
@link URL 类似于license 但还可以通过link找到文档中的更多个详细的信息
@name 变量别名 为某个变量指定别名
@magic   phpdoc.de compatibility
@package 封装包的名称 一组相关类、函数封装的包名称
@param 如 [$username] 用户名 变量含义注释
@return 如 返回bool 函数返回结果描述,一般不用在void(空返回结果的)的函数中
@see 如 Class Login() 文件关联的任何元素(全局变量,包括,页面,类,函数,定义,方法,变量)。
@since version 记录什么时候对文档的哪些部分进行了更改
@static   记录静态类、方法
@staticvar   在类、函数中使用的静态变量
@subpackage   子版本
@throws   某一方法抛出的异常
@todo   表示文件未完成或者要完善的地方
@var type 文档中的变量及其类型
@version   文档、类、函数的版本信息

实例参考

下面参考一下两个开源项目的 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 介绍与安装 几个 IntelliJ IDEA 小技巧