phpdocumentor2中tag标签说明文档

翻译了下phpdocumentor2的标签说明文档，不过在测试时候发现phpdoc2的bug真的好多，暂时不适合作为完善软件使用。

建议使用pear install phpdocumentor来安装1.4.4版使用

文档更新时间：2013-09-24

首先要明白一个结构元素Structural Elements 的概念：

结构元素是指程序结构中理应在它之前添加一些相关注释块的程序的结构元素

如下面这些：

· namespace

· require(_once)

· include(_once)

· class

· interface

· Trait 相关特性

· function (including methods)

· property

· constant

下面介绍phpdocumentor2支持的tag：

@api 

用来声明一个结构元素是否可被用作第三方API。

例如在一个库或框架里的被提供给第三方的公用API一个函数注释块前，使用@api来声明即可

@author 

作者信息

格式：@author [name] [<email address>]  

例子：@author yukon12345 <[email protected]>

解释：email为可选，一般要用<>来括住email来更符合标准

@category 

此tag将在将来的版本中被弃用，作用同@package

@copyright

 版权信息

例子 @copyright 1997-2005 The PHP Group

@deprecated  

弃用声明

格式 ：@deprecated [<version>] [<description>] 

例子：@deprecated 1.0.0 No longer used by internal code and not recommended.

解释：Version的版本指的是此结构元素在此版本前被支持，在此版本后将被弃用

@example

(此tag在phpdocumentor2中并不能完美支持。) 这个tag指明示例代码文件的路径，来说明结构元素的使用方法等。

格式：@example [location] [<start-line> [<number-of-lines>] ] [<description>]

or 单行：

{@example [location] [<start-line> [<number-of-lines>] ] [<description>]}

解释：其中location是必须的，可以是绝对、相对的文件路径或URI。如果是文件路径的话需要用双引号围起来标明。Phpdocumentor将会查找相应的URI和文件路径，来获取文件：1配置文件或命令行所在文件夹，2源文件目录，3工程文件根目录中一个example文件夹

start-line必须是一个正整数。它指明了起始的行数。指定从示例代码文件的多少行来读取。

number-of-lines 指定示例代码有多少行。省略默认到文件结尾

例子：

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

源文件输出

解释：加入此tag后会将源文件编码压缩，并可以在文档中显示。注释块加入@filesource 即可（yukon12345：不过据我观察，就算不加也还是可以点击</>的标志来查看。。。。而且这个功能只支持firefox。。无语，又是一个bug）

@global 

全局变量

格式 :@global [Type] [description] 

解释：预定的标签，2.0版本并不支持。在将来的版本中可能会生效。不过你先加上也不会有什么事。但是在一个注释块中只能使用一次global标签。而且注释块必须紧接着全局变量。

@ignore

忽略处理tag

解释：用来告诉phpdocumentor不要处理输出此注释块。通常用在条件语句中防止重复输出。

例子：if ($ostest) {

     /**

      * This define will either be 'Unix' or 'Windows'

      */

     define("OS","Unix");

 } else {

     /**OS为windows。这里的注释可以供程序员查看，phpdocumentor不输出

      * @ignore

      */

     define("OS","Windows");

 }

@internal 

内部声明

解释：用来标明结构元素仅供程序或库内使用，也可以用作在一段长描述中插入一个内部文本块

格式：

@internal [description]

或者行内格式

{@internal[description]}}

因为行内格式的internal标签可以再包含其他行内格式的标签，因此要用{}括起来

解释：这个标签就是在注释块里声明一部分不输出在文档的信息。比如一些重要解释信息但是不适合发布公开。另外还可以用来标明局部变量或内部函数。

 

@license 

授权许可声明

用来指明结构元素或其他子元素所使用的授权许可。不过一般在文件范围内声明就可以了，如果给过多的结构元素都设上声明会造成混乱。另外，每个不同的许可声明必须分别使用tag声明

格式：

@license [<url>] [name]

/**例子

  * @license GPL

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

  */

@link

链接声明

这个tag用来指明结构元素和网站之间的自定义关系，用一个绝对URI来定义。

注意：此元素的行内格式只支持URI格式，而不支持结构元素。这是一个已知的问题，将会在2.1的版之前解决。

格式：

@link [URI] [<description>]

or inline

{@link [URI] [<description>]}\

解释：

 

 

@method

用来一个类包含魔术函数__call()的情况下，这个tag可以指明一些明确的使用方法。

解释：php的重载机制比较特别，需要用到__call()来实现，因此声明一些重载函数时候可以使用这个标签来说明，另外动态的getter和setter也可以用它来指明。详情点击标签看例子。

@package

包信息

解释：用来逻辑细分结构元素。类似java中package的功能。一个块内只能使用一次。尽可能使其深度低于6层。使用此tag的结构元素会被组合成一个逻辑分类。详情点击标签看例子。

@param

参数声明

格式：@param [Type] [name] [<description>]

解释：用的最多的tag之一了。标示说明函数和方法的一个参数。其中type和name是必须的。如果type类型是某class并且phpdoc有生成其文档，那么会生成一个link链接。

@property-read

只读属性声明

@property-read [Type] [name] [<description>]

解释：声明类中的某些“魔术”属性为只读。Php的类是用__get()魔术方法来设置只读属性的，这个tag可以标记只读属性。通常在含有__get()方法的子类前，设置此tag注释来提醒。此tag只能用于类或接口的注释块。

@property-write

只写属性声明。解释格式同上

@property

“魔术”可读写属性声明。这种属性可能在读写时被__get()或__set()做一些其他处理。详细请参考getter和setter。相关解释类似只读属性声明。

@return

格式：@return [Type] [<description>]

返回值，没什么好解释的。可以使用多行格式，通常建议在每个函数和方法前都要加一个此标签，除了构造器和无返回的函数/方法。

@see

参考引用（yukon12345：此标签貌似有bug无法显示）

格式：@see [URI | FQSEN] [<description>]、

See标签的作用就是标示一个参考引用，参数可以是URI或FQSEN，FQSEN指的是Fully Qualified Structural Element Name 全限定名的结构元素 即包含命名空间，类等全地址信息的结构元素比如\My\Space\MyClass::myMethod()。使用see后生成的文档会出现一个超链指向相关地址或方法。

@since

注意：支持尚不完善

格式:@since [version] [<description>]

解释：指出被注释的结构元素从哪个版本起被支持。也可以描述结构元素的各版本变更信息。

@source

显示结构元素的源代码（yukon12345：又是一个bug，貌似查看按钮无效）

格式:@source [<start-line> [<number-of-lines>] ] [<description>]

解释：start-line 显示注释块注释的结构元素的源代码起始行，必须是正整数number-of-lines源代码的总行数。如无设置默认从start-line开始到结构元素源码结尾。

@subpackage

注意 ：此标签将在将来的版本中被弃用。作用同@package标签

@throws

异常信息说明。没有什么特殊的地方。一般在可能抛出异常的结构元素前最好都加上。并且说明每一种异常。

@todo

格式：@todo [description]

标示此结构元素仍在开发中。Todo标签的description是必不可少的。次标签也可用于多人协同时的沟通意图。另外phpdocumentor会自动生成一个集成所有todo的结构元素报表。

@uses & @used-by

声明了一种与另一个结构元素的参考引用。

格式：@uses [FQSEN] [<description>]

解释：和@see类似，都代表了与另一种结构元素的关系。但是@see没有反向链接。如果使用了@uses标签，phpdocumentor会自动在相关结构元素处生成一个@used-by标签

@var

用来指明类的一个属性。

格式：

@var [Type] [<description>]

@var [Type] [name] [<description>]

[<summary>]

@var [Type] [<description>]

[<summary>]

@var [Type] [name] [<description>]

解释：之前可以加个summary综述来介绍。一个注释块只能用一个var标签。

@version

标示当前结构元素的版本号（yukon12345：此标签有bug，无法显示版本号。。）

格式：@version [<vector>] [<description>]

解释：verctor版本号的使用要符合语义版本控制标准。参见：http://www.semver.org.