Home  >  Article  >  Backend Development  >  PHPDocumentor annotation specification organization_PHP tutorial

PHPDocumentor annotation specification organization_PHP tutorial

WBOY
WBOYOriginal
2016-07-13 10:21:28865browse

PHPDocumentor annotation specification organization

Can you write comments? This problem has been bothering me since I started writing code, and I believe it is also bothering other students. In the past, there was no effective standard for writing comments, which caused a lot of trouble for maintenance and collaborative development. Until recently, I read the comment standard of phpdocumentor.

The following summarizes the comment standards of phpdocumentor:


Type (data type):

    1. string string type
    2. integer or int integer
    3. boolean or bool Boolean type true or false
    4. float or double floating point type
    5. object object
    6. mixed mixed type is used when no type is specified or the type is uncertain
    7. array array
    8. resource resource type (such as returned by database query)
    9. void null value (controller return value is often used)
    10. null null type
    11. callable callback function
    12. false or true Use
    13. when only true or fasle is returned
    14. self 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

      版本

      Tag
      Element Description
      api Methods Declare interface
      author Any Author information
      category File, Class Categories a series of elements together
      copyright Any Copyright Information
      deprecated Any The declaration element is deprecated and may be removed in a future version
      example Any Example
      filesource File File Resources
      global Variable Declare a set variable
      ignore Any Ignore the current element (when phpdocumentor generates the document)
      internal Any Declare a value as an integer, or set an application's default value as an integer
      license File, Class State license type
      link Any Declare a link related to the current element
      method Class Declare which magic methods of the current class can be called
      package File, Class Declare the package to which the current element belongs
      param Method, Function Declare a parameter of the current element
      property Class Declare the properties of the current class that have magic methods that can be called
      property-read Class Declare which magic methods the current class has to read properties
      property-write Class Declare which magic methods the current class has to set properties
      return Method, Function Return value
      see Any Explain that the current element parameters refer to other sites or elements
      since Any Declares which version the current element starts from
      source Any, except File Show the source code of the current element
      subpackage File, Class Category the current elements
      throws Method, Function Describes the exception thrown by the current element
      todo Any Describes development activity for the current element
      uses Any References an associated element
      var Properties Declare attributes
      version Any Version

       

       

      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>
        */</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 &#39;Unix&#39; or &#39;Windows&#39;
            */
           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 string|null The label&#39;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
        *     &#39;array&#39;.
        *
        * @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
       {
           <...>
       }

       

       

       

       

       

       

www.bkjia.comtruehttp://www.bkjia.com/PHPjc/857042.htmlTechArticlePHPDocumentor 注释规范整理 你会写注释么?从我写代码开始,这个问题就一直困扰着我,相信也同样困扰着其他同学。以前的写注释总是没有...
Statement:
The content of this article is voluntarily contributed by netizens, and the copyright belongs to the original author. This site does not assume corresponding legal responsibility. If you find any content suspected of plagiarism or infringement, please contact admin@php.cn