phpDocumentor生成文档

截止2016.10.1日，phpdocmentor只有2.9.0支持php7

基本使用方法

phpdoc -d [目录位置] -t [输出位置]     #输出位置可选

docblock注释

多行注释风格

 <?php
 /**
  * A summary informing the user what the associated element does.
  *
  * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
  * and to provide some background information or textual references.
  *
  * @param string $myArgument With a *description* of this argument, these may also
  *    span multiple lines.
  *
  * @return void
  */
  function myFunction($myArgument)
  {
  }

• summary简要介绍
  需要以.(dot)然后紧跟一个空行结束

• description简要描述
  遇到*/或者tag结束

• tag标签
  以@开头的一些有意义标签

文档级别的注释

<?php
/**
 * I belong to a file
 */

/**
 * I belong to a class
 */
class Def
{
}

下边是属于类的注释

<?php
/**
 * I belong to a class
 */

class Def
{
}

常规标签

• @package
  描述class所属的namespace

• @access
  public, private or protected

• @author
  作者信息：

`@author	jcuan <heheda@heheda.com>`

• @copyright
  文档版权信息

 @copyright	Copyright (c) 2014 - 2016, British Columbia Institute of Technology (http://bcit.ca/)

• @deprecated
  以后将被废除的方法

/**
 * @deprecated
 * @deprecated 1.0.0
 * @deprecated No longer used by internal code and not recommended.
 * @deprecated 1.0.0 No longer used by internal code and not recommended.
 */
 function count()
 {
     <...>
 }

• throws
  @throws [Type] [<description>]

 /**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $array Array structure to count the elements of.
  *
  * @throws InvalidArgumentException if the provided argument is not of type
  *     'array'.
  *
  * @return int Returns the number of elements.
  */
 function count($items)
 {
     <...>
 }

• @license
  @license [<url>] [name]

 /**
  * @license GPL
  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  */

• @method
  用在使用了__call()魔术方法的类
  @method [return type] [name]([[type] [parameter]<, ...>]) [<description>]

 class Parent
 {
     public function __call()
     {
         <...>
     }
 }

 /**
  * @method string getString()
  * @method void setInteger(integer $integer)
  * @method setString(integer $integer)
  */
 class Child extends Parent
 {
     <...>
 }

• @param
  函数参数描述@param [Type] [name] [<description>]

 /**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $items Array structure to count the elements of.
  *
  * @return int Returns the number of elements.
  */
 function count(array $items)
 {
     <...>
 }

• @return
  @return [Type] [<description>]

• @see
  网址或其他方法的引用
  @see [URI | FQSEN] [<description>]

/**
  * @see http://example.com/my/bar Documentation of Foo.
  * @see MyClass::$items           For the property whose items are counted.
  * @see MyClass::setItems()       To set the items for this collection.
  *
  * @return integer Indicates the number of items.
  */
 function count()
 {
     <...>
 }

• @since
  本方法从哪个版本开始出现
  @since [version] [<description>]

• @todo
  接下来要做的
  @todo [description]

• @var
  函数变量
  @var [“Type”] [$element_name] [<description>]

class Foo
{
  /**
   * @var string $name        Should contain a description
   * @var string $description Should contain a description
   */
  protected $name, $description;
}

• @version
  当前版本
  @version [<vector>] [<description>]

内联标签（inline tags）

常规标签不同，行内标签不要求出现在新行的开头，而可以出现在文本流中

Syntax
@link [URI] [<description>]
or inline
{@link [URI] [<description>]}