PHP注释标记整理
<h1 id="什么是注释标记">什么是注释标记</h1><p>我们在平常写代码或看别人写的代码时, 在方法的说明注释中经常会有这样的注释:</p>
<pre><code class="language-php">/**
* @param $num
* @return array
*/
</code></pre>
<p>上面的<em>@param</em> <em>@return</em> 就是注释标记</p>
<p>注释标记用于生成文档, param指明需要接收的参数, return指明返回值</p>
<p>在使用 phpDocumentor 等工具生成文档时, 会识别相关注释, 而且IDE也会识别, 在编码的过程中会给出提示.</p>
<h1 id="php注释标记总结">PHP注释标记总结</h1>
<ul>
<li>@api: 提供给第三方使用的接口</li>
<li>@author: 标明作者</li>
<li>@param: 参数</li>
<li>@return: 返回值</li>
<li>@todo: 待办</li>
<li>@version: 版本号</li>
<li>@inheritdoc: 文档继承</li>
<li>@property: 类属性</li>
<li>@property-read: 只读属性</li>
<li>@property-write: 只写属性</li>
<li>@const: 常量</li>
<li>@deprecated: 过期方法</li>
<li>@example: 示例</li>
<li>@final: 标识类是终态, 禁止派生</li>
<li>@global: 指明引用的全局变量</li>
<li>@static: 标识类、方法、属性是静态的</li>
<li>@ignore: 忽略</li>
<li>@internal: 限内部使用</li>
<li>@license: 协议</li>
<li>@link: 链接,引用文档等</li>
<li>@see: 与 link 类似, 可以访问内部方法或类</li>
<li>@method: 方法</li>
<li>@package: 命名空间</li>
<li>@since: 从指定版本开始的变动</li>
<li>@throws: 抛出异常</li>
<li>@uses: 使用</li>
<li>@var: 变量</li>
<li>@copyright: 版权声明</li>
</ul>
<p><strong>@author</strong></p>
<p>标明作者</p>
<pre><code class="language-php">/*
* @author hujing <hu@163.com>
* hujing: 作者名
* hu@163.com: 邮箱
*/
</code></pre>
<p><strong>@copyright</strong></p>
<p>版权声明</p>
<p><code>@copyright [描述]</code></p>
<p><strong>@deprecated</strong></p>
<p>标明方法是不建议使用的、已过期的或将要删除的</p>
<pre><code class="language-php">/*
* 语法:
* @deprecated [版本号] [描述]
* eg:
* @see Class::test()
* @deprecated 2.0 将被弃用,请使用test方法
*/
</code></pre>
<p><strong>@inheritdoc</strong></p>
<p>会继承父类文档, 且子类出现冲突文档时重写父类文档</p>
<p><strong>@internal</strong></p>
<p>标识此类或方法仅限当前文件使用</p>
<p><code>@description [描述]</code></p>
<p><strong>@link</strong></p>
<p>指明外部链接, 必须给出完整url</p>
<p><code>@link [描述]</code></p>
<p><strong>@see</strong></p>
<p>此链接不光可以跳转到外部链接, 还可以跳转到内部的指定方法等, 如: <em>class::method</em></p>
<p><code>@see [描述]</code></p>
<p><strong>@var</strong></p>
<p>定义数据的类型</p>
<p><code>@var [类型] [变量名] [描述]</code></p>
<pre><code class="language-php">/**
* 可以指定变量的类型
* @var array 名称列表
* 也可以指定变量名, 指定变量时数组或空
* @var array|null $nameList 名称列表
*/
</code></pre>
<p>类型列表如下:</p>
<ul>
<li>string: 字符串</li>
<li>int/integer: 数字</li>
<li>boolean/bool: 布尔</li>
<li>float/double: 浮点</li>
<li>object: 对象实例</li>
<li>TestClass: 指定类</li>
<li>mixed: 任意类型</li>
<li>array: 数组</li>
<li>TestClass[]: 指定类型数组</li>
<li>resource: 文件资源</li>
<li>void: 无</li>
<li>null:</li>
<li>callable: 回调函数</li>
<li>function: 方法</li>
<li>self/$this: 当前实例</li>
</ul>
<p><strong>@throws</strong></p>
<p>抛出异常</p>
<p><code>@throws [类型] [描述] </code></p>
<p><strong>@method</strong></p>
<p>类注释, 标明该类可以调用的方法, 可以令IDE自动提示等</p>
<pre><code class="language-php">/**
* @method string test(int num) 测试方法
*/
</code></pre>
<p><strong>@param</strong></p>
<p>标识参数信息, 类型可参考 @var</p>
<p><code>@param [类型] [名称] [描述]</code></p>
<p><strong>@property</strong></p>
<p>类属性, 指明可以直接访问与修改的类属性, 私有属性需要通过 <em>__get</em> <em>__set</em> 魔术方法设置与访问, 类型参考 @var</p>
<p><code>@property [类型] [名称] [描述]</code></p>
<p><strong>@property-read</strong></p>
<p>类属性, 指明只读的类属性, 私有属性需要通过 <em>__get</em>魔术方法访问, 类型参考 @var</p>
<p><strong>@property-write</strong></p>
<p>类属性, 指明只写的类属性, 私有属性需要通过 <em>__set</em>魔术方法设置, 类型参考 @var</p>
<p><strong>@return</strong></p>
<p>标识方法的返回值, 类型参考 @var</p>
<p><code>@return [类型] [描述]</code></p>
<p><strong>@global</strong></p>
<p>标明用到的全局变量</p>
<p><code>@global [类型] [名称] [描述]</code></p>
<p><strong>@ignore</strong></p>
<p>标明生成文档是忽略的值</p>
<p><strong>@users</strong></p>
<p>标明使用到了哪些值</p>
<pre><code class="language-php">/**
* @users Class::$num 使用此属性计数
*/
</code></pre>
<hr>
<p>有一些注释没有给出说明, 是因为个人不是常用, 当然还有一些注释没有总结到, 后面用到了再总结.</p><br><br>
来源：https://www.cnblogs.com/hujingnb/p/11117266.html
頁:
[1]