PHPDOC

51漂泊

PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档，也可以帮助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之类的 集成开发环境 理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。
PHPDoc 可同时支持 面向对象 的和 面向过程的 代码。

以上摘自维基百科

简单来说 PHPDOC 可以用来自动生成 API 文档。主流的 IDE 都会识别它，并在你 coding 中给予你相应的智能提示。使用 PHPDOC 有以下好处

• 让你的代码更加规 zhuang 范 bi，更易于理解

• 让你的 IDE 更懂你的代码，更加智能的提示和自动完成

• 如需 API 手册，可使用 phpDocumentor 来自动生成

  
  

还等什么？快跟我一起来学习又好用又有逼格的 phpDoc 吧！

有关 phpDoc 的完整文档位于 phpDocumentor 官网。以下内容由我个人理解、提炼而来，而且我也还在学习中，如有失误还请各位多多指教

1. @api
   
2. 表示这是一个提供给第三方使用的 API 接口
   
3. 
   
4. @author
   
5. 作者
   
6. 格式 @author [名称] [<邮箱>]
   
7. 例如 @author mokeyjay <i@mokeyjay.com>
   
8. 
   
9. @copyright
   
10. 版权声明。例如很多网站底部都有
    
11. 格式 @copyright [描述]
    
12. 例如 @copyright 1949-2016 China
    
13. 
    
14. @deprecated
    
15. 不建议使用的、已过期的、将被删除的
    
16. 格式 @deprecated [<版本号>] [<描述>]
    
17. 例如 @deprecated 1.0.0 新版本将不再包含此函数
    
18. 如果它是被其他方法所取代了，建议添加 @see 标记
    
19. 
    
20. @example
    
21. 例子、示例、用例。也可表示方法返回值的例子
    
22. 格式 @example [位置] [<起始行号> [<行数>] ] [<描述>]
    
23. 例如 @example demo.php 10 3 使用示例
    
24. 
    
25. @filesource
    
26. 没看懂，如果你们看懂了请告诉我。传送门
    
27. 
    
28. @global
    
29. 全局变量
    
30. 格式 @global [类型][名称] @global [类型][描述]
    
31. 我怀疑这里是源文档打错了，大概应该是
    
32. 格式 @global [类型][名称][描述]
    
33. 类型 @global string name 用户名
    
34. 
    
35. @ignore
    
36. 忽略
    
37. 格式 @ignore [<描述>]
    
38. 例如你在 if 和 else 的语句块中定义分别同一个变量但值不同时，可以通过此标记让 phpDocumentor 忽略其中一个，以免生成重复的文档。例如
    
39. 
    
40. if ($ostest) {
    
41.      /**
    
42.       * This define will either be 'Unix' or 'Windows'
    
43.       */
    
44.      define("OS","Unix");
    
45. } else {
    
46.      /**
    
47.       * @ignore
    
48.       */
    
49.      define("OS","Windows");
    
50. }
    
51. @internal
    
52. 仅限内部使用的
    
53. 格式 @internal [描述]
    
54. 例如 @internal 仅限内部测试使用
    
55. 
    
56. @license
    
57. 协议，很常见的啦
    
58. 格式 @license [<url>] [名称]
    
59. 例如 @license GPL
    
60. 
    
61. @link
    
62. 链接，可用于辅助说明、引用文档等
    
63. 格式 @link [url] [<描述>]
    
64. 例如 @link http://g.cn 不懂滚去问谷歌，别来烦我
    
65. 
    
66. @method
    
67. 方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE 无法自动提示出来，这时就可以通过写 @method 标记来告诉 IDE 我这类里有哪些方法
    
68. 格式 @method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
    
69. 例如 @method string google(string $question) 向谷歌提问，返回答案内容
    
70. 
    
71. @package
    
72. 包。但 php 没有包，所以就用来表示命名空间
    
73. 例如 @package yii\base\db
    
74. 
    
75. @param
    
76. 参数，用于函数和方法注释里的标记
    
77. 格式 @param [Type] [name] [<description>]
    
78. 例如 @param string title 文章标题
    
79. 
    
80. @property
    
81. 类属性，与 @method 类似，可以告诉 IDE 我这类里有哪些属性
    
82. 格式 @property [Type] [name] [<description>]
    
83. 例如 @property int id 用户id
    
84. 
    
85. @property-read
    
86. 只读的属性。例如__get 魔术方法能够取到的属性
    
87. 格式 @property-read [Type] [name] [<description>]
    
88. 例如 @property-read int id 用户id
    
89. 
    
90. @property-write
    
91. 只可写的属性。例如__set 魔术方法能够设置的属性
    
92. 格式 @property-write [Type] [name] [<description>]
    
93. 例如 @property-write string name 用户名
    
94. 
    
95. @return
    
96. 返回值
    
97. 格式 @return [类型] [<描述>]]
    
98. 例如 @return array 结果数组
    
99. 
    
100. @see
     
101. 参考，类似 @link，可与 @deprecated 联动
     
102. 格式 @see [url或完整方法名] [<描述>]
     
103. 例如 @see \yii\base\db::tableName() 旧方法table_name已弃用，请使用此方法替代
     
104. 
     
105. @since
     
106. 从 xx 版本开始。例如从 1.0 之后添加了 xx 功能、删除了 xx 参数等
     
107. 格式 @since [1.0.0] [<描述>]
     
108. 例如 @since 1.0.2 添加了$b参数
     
109. 
     
110. @source
     
111. 没看懂，如果你们看懂了请告诉我。传送门
     
112. 
     
113. @throws
     
114. 可能会抛出的错误类型
     
115. 格式 @throws [类型] [<描述>]
     
116. 例如 @throws LifeException 没钱了，好想死啊
     
117. 
     
118. @todo
     
119. 待办。提示自己或他人还需要做些什么
     
120. 格式 @todo [描述]
     
121. 例如 @todo 这个类还没做异常处理
     
122. 
     
123. @uses
     
124. 使用
     
125. 格式 @uses [完整方法名] [<描述>]
     
126. 例如 @uses \yii\base\db::$count 使用此属性计数
     
127. 
     
128. @var
     
129. 变量
     
130. 格式 @var [类型] [变量名] [<描述>]
     
131. 例如 @var int id 用户id
     
132. 
     
133. @version
     
134. 版本号
     
135. 格式 @version [<载体>] [<描述>]
     
136. 例如 @version 1.0.1 2016-07-03更新
     
137. 或者 @version GIT:1f3197d01 来自GIT分支1f3197d01
     

复制代码