PHPDocumentor 注释规范整理

     你会写注释么?从我写代码开始,这个问题就一直困扰着我,相信也同样困扰着其他同学。以前的写注释总是没有一套行之有效的标准,给维护和协同开发带了许多麻烦,直到最近读到了phpdocumentor的注释标准。

     

    下面对phpdocumentor的注释标准进行总结:


    Type(数据类型):

     

    1. string 字符串类型
    2. integer or int 整型
    3. boolean or bool 布尔类型 true or false
    4. float or double 浮点类型
    5. object 对象
    6. mixed 混合类型 没有指定类型或不确定类型时使用
    7. array 数组
    8. resource 资源类型 (如数据库查询返回)
    9. void 空值(控制器返回值经常使用)
    10. null null类型
    11. callable 回调函数
    12. false or true 只返回true or fasle 时使用
    13. self 自身

     

    Tags(标签):

     

    Tag

    Element

    Description

    api

    Methods

    声明接口

    author

    Any

    作者信息

    category

    File, Class

    将一系列的元素分类在一起

    copyright

    Any

    版权信息

    deprecated

    Any

    声明元素已被弃用,可以在将来的版本中删除

    example

    Any

    示例

    filesource

    File

    文件资源

    global

    Variable

    声明一个全集变量

    ignore

    Any

    忽略当前元素 phpdocumentor 生成文档时)

    internal

    Any

    声明一个值为整形,或者设置一个应用的默认值为整型

    license

    File, Class

    声明许可类型

    link

    Any

    声明一个和当前元素有关的链接

    method

    Class

    声明当前类那些魔术方法可以被调用

    package

    File, Class

    声明当前元素所属的包

    param

    Method, Function

    声明当前元素的一个参数

    property

    Class

    声明当前类有那些魔术方法可以被调用属性

    property-read

    Class

    声明当前类有那些魔术方法可以读取属性

    property-write

    Class

    声明当前类有那些魔术方法可以设置属性

    return

    Method, Function

    返回值

    see

    Any

    说明当前元素参数引用于其他站点或元素

    since

    Any

    声明当前元素始于于哪个版本

    source

    Any, except File

    展示当前元素的源码

    subpackage

    File, Class

    将当期元素分类

    throws

    Method, Function

    说明当前元素抛出的异常

    todo

    Any

    说明当前元素的开发活动

    uses

    Any

    引用一个关联元素

    var

    Properties

     声明属性

    version

    Any

    版本

     

     

    Example(示例):

     

    // =============================

     

    @api

     

    /**
      * This method will not change until a major release.
      *
      * @api
      *
      * @return void
      */
      function showVersion()
      {
         <...>
      }

    // =============================

     

    @author

     

    /**
      * @author My Name
      * @author My Name <[email protected]>
      */

     

    // =============================

     

    @category

     

     /**
      * Page-Level DocBlock
      *
      * @category MyCategory
      * @package  MyPackage
      */

     

    // =============================

     

    @copyright

     

    /**
      * @copyright 1997-2005 The PHP Group
      */

     

    // =============================

     

    @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()
     {
         <...>
     }

     

    // =============================

     

    @example

     

    /**
      * @example example1.php Counting in action.
      * @example http://example.com/example2.phps Counting in action by a 3rd party.
      * @example "My Own Example.php" My counting.
      */
     function count()
     {
         <...>
     }

     

    // =============================

     

    @filesource

     

    /**
      * @filesource
      */

     

    // =============================

     

    @global phpdocumentor2.0不支持

     

    // =============================

     

    @ignore

     

    if ($ostest) {
         /**
          * This define will either be 'Unix' or 'Windows'
          */
         define("OS","Unix");
     } else {
         /**
          * @ignore
          */
         define("OS","Windows");
     }

     

    // =============================

     

    @internal

     

     /**
      * @internal
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

     /**
      * Counts the number of Foo.
      *
      * {@internal Silently adds one extra Foo to compensate for lack of Foo }}
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

    // =============================

     

    @license

     

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

     

    // =============================

     

    @link

     

    /**
      * @link http://example.com/my/bar Documentation of Foo.
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

    /**
      * This method counts the occurrences of Foo.
      *
      * When no more Foo ({@link http://example.com/my/bar}) are given this
      * function will add one as there must always be one Foo.
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

    // =============================

     

    @method

     

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

     

    // =============================

     

    @package

     

    /**
      * @package PSR\Documentation\API
      */

     

    // =============================

     

    @param

     

    /**
      * 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)
     {
         <...>
     }

     

    // =============================

     

    @property

     

    class Parent
     {
         public function __get()
         {
             <...>
         }
     }
     
     /**
      * @property string $myProperty
      */
     class Child extends Parent
     {
         <...>
     }

     

    // =============================

     

    @property-read

     

    class Parent
     {
         public function __get()
         {
             <...>
         }
     }
     
     /**
      * @property-read string $myProperty
      */
     class Child extends Parent
     {
         <...>
     }

     

    // =============================

     

    @property-write

     

     class Parent
     {
         public function __set()
         {
             <...>
         }
     }
     
     /**
      * @property-write string $myProperty
      */
     class Child extends Parent
     {
         <...>
     }

     

    // =============================

     

    @return

     

    /**
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

    /**
      * @return string|null The label's text or null if none provided.
      */
     function getLabel()
     {
         <...>
     }

     

    // =============================

     

    @see

     

     /**
      * @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 1.0.1 First time this was introduced.
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

     /**
      * @since 1.0.2 Added the $b argument.
      * @since 1.0.1 Added the $a argument.
      * @since 1.0.0
      *
      * @return void
      */
     function dump($a, $b)
     {
         <...>
     }

     

    // =============================

     

    @source

     

    /**
      * @source 2 1 Check that ensures lazy counting.
      */
     function count()
     {
         if (null === $this->count) {
             <...>
         }
     }

     

    // =============================

     

    @subpackage

     

    /**
      * @package PSR
      * @subpackage Documentation\API
      */

     

    // =============================

     

    @throws

     

    /**
      * 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)
     {
         <...>
     }


    // =============================

     

    @todo

     

     /**
      * Counts the number of items in the provided array.
      *
      * @todo add an array parameter to count
      *
      * @return int Returns the number of elements.
      */
     function count()
     {
         <...>
     }

     

    // =============================

     

    @uses

     

    /**
      * @uses MyClass::$items to retrieve the count from.
      *
      * @return integer Indicates the number of items.
      */
     function count()
     {
         <...>
     }

     

    // =============================

     

    @var

     

     class Counter
     {
    /**
      * @var
      */
    public $var;
     }

     

    // =============================

     

    @version

     

    /**
      * @version 1.0.1
      */
     class Counter
     {
         <...>
     }

     

     /**
      * @version GIT: $Id$ In development. Very unstable.
      */
     class NeoCounter
     {
         <...>
     }

     

    // =============================

     

    phpdocumentor手册:http://www.phpdoc.org/docs/latest/index.html


    (本人英语水平有限,如果翻译不当,请提出,定当及时修正)


PHPDocumentor 注释规范整理,古老的榕树,5-wow.com

郑重声明:本站内容如果来自互联网及其他传播媒体,其版权均属原媒体及文章作者所有。转载目的在于传递更多信息及用于网络分享,并不代表本站赞同其观点和对其真实性负责,也不构成任何其他建议。