你會(huì)寫注釋么？從我寫代碼開始，這個(gè)問題就一直困擾著我，相信也同樣困擾著其他同學(xué)。以前的寫注釋總是沒有一套行之有效的標(biāo)準(zhǔn)，給維護(hù)和協(xié)同開發(fā)帶了許多麻煩，直到最近讀到了phpdocumentor的注釋標(biāo)準(zhǔn)。

下面對(duì)phpdocumentor的注釋標(biāo)準(zhǔn)進(jìn)行總結(jié)：

Type（數(shù)據(jù)類型）:

• 1. string 字符串類型
  2. integer or int 整型
  3. boolean or bool 布爾類型 true or false
  4. float or double 浮點(diǎn)類型
  5. object 對(duì)象
  6. mixed 混合類型 沒有指定類型或不確定類型時(shí)使用
  7. array 數(shù)組
  8. resource 資源類型 （如數(shù)據(jù)庫查詢返回）
  9. void 空值（控制器返回值經(jīng)常使用）
  10. null null類型
  11. callable 回調(diào)函數(shù)
  12. false or true 只返回true or fasle 時(shí)使用
  13. self 自身

       

      Tags（標(biāo)簽）:

       

      Tag	Element	Description
      api	Methods	聲明接口
      author	Any	作者信息
      category	File, Class	將一系列的元素分類在一起
      copyright	Any	版權(quán)信息
      deprecated	Any	聲明元素已被棄用,可以在將來的版本中刪除
      example	Any	示例
      filesource	File	文件資源
      global	Variable	聲明一個(gè)全集變量
      ignore	Any	忽略當(dāng)前元素 （phpdocumentor 生成文檔時(shí)）
      internal	Any	聲明一個(gè)值為整形，或者設(shè)置一個(gè)應(yīng)用的默認(rèn)值為整型
      license	File, Class	聲明許可類型
      link	Any	聲明一個(gè)和當(dāng)前元素有關(guān)的鏈接
      method	Class	聲明當(dāng)前類那些魔術(shù)方法可以被調(diào)用
      package	File, Class	聲明當(dāng)前元素所屬的包
      param	Method, Function	聲明當(dāng)前元素的一個(gè)參數(shù)
      property	Class	聲明當(dāng)前類有那些魔術(shù)方法可以被調(diào)用屬性
      property-read	Class	聲明當(dāng)前類有那些魔術(shù)方法可以讀取屬性
      property-write	Class	聲明當(dāng)前類有那些魔術(shù)方法可以設(shè)置屬性
      return	Method, Function	返回值
      see	Any	說明當(dāng)前元素參數(shù)引用于其他站點(diǎn)或元素
      since	Any	聲明當(dāng)前元素始于于哪個(gè)版本
      source	Any, except File	展示當(dāng)前元素的源碼
      subpackage	File, Class	將當(dāng)期元素分類
      throws	Method, Function	說明當(dāng)前元素拋出的異常
      todo	Any	說明當(dāng)前元素的開發(fā)活動(dòng)
      uses	Any	引用一個(gè)關(guān)聯(lián)元素
      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 
        */

       

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

       

      @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 PSRDocumentationAPI
        */

       

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

      @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 stringnull 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 DocumentationAPI
        */

       

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

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

  14. 關(guān)鍵字：PHP、數(shù)據(jù)庫、注釋