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 <my.name@example.com>
      */

     

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

     

    @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


    (我有限的英語水平,假設不當翻譯,請建議,當然,及時修正)



注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2020 ITdaan.com