PHP 注释 生成文档

phpDocumentor 注释标准

可以注释的地方

• namespace
• require(_once)
• include(_once)
• class
• interface
• trait
• function (including methods)
• property
• constant
• variables, both local and global scope.

 一个代码块包括三个部分

1. 总结；一行总结功能用处
2. 描述；扩展描述的记录元件的功能； 使用markdown样式   如：解释算法、代码示例、阵列规格、与其他元素、许可证信息
3. 标签；此元素的特性的一系列参数；如参数和返回值

 

注释标签：

@api
@author
@category
@copyright
@deprecated
@example
@filesource
@global
@ignore
@internal
@license
@link
@method
@package
@param
@property
@property-read
@property-write
@return
@see
@since
@source
@subpackage
@throws
@todo
@uses & @used-by
@var
@version

 

写法

 

@return (int|string)[]

@return int|null
@return int[]

@return void

 

文件头部注释

@version 0.1.0   版本
建议：Major.Minor.Patch的版本命名方式，也就是Breaks.Features.Fixes

@author cgjcgs  cgjcgs@gmail.com   作者
参数： 姓名 、email

@date 11/22/15　　　　日期

@since 0.1.0 11/22/15 cgjcgs : 新增getLatest3Posts()　　改版记录
参数： 版本号、修改日期 、修改者名称、 ：后面为简单注释
很多版本 可以加上多個@since

###  完整示例  ###
/**
 * 示例类
 *
 * @versio 0.1.0
 * @author cgjcgs cgjcgs@163.com 
 * @data 2017/09/20
 * @since 0.1.1 2017/09/22 cgjcgs : bug修复
 */

 

类注释

@package  命名空间

@method   方法
@method className first()
一般不用 在使用__call()或__callStatic() 动态产生时 编辑器抓取不到 也不容易看出来 需要doc描述

@property 
@property string $name
一般不用 在使用__get()或__set() 动态产生时 编辑器抓取不到 也不容易看出来 需要doc描述

 

属性 property 注释

@var Post 注入的post model
protected $Post;

参数： 类型 、 描述

 

方法 method 注释

@param string $field 排序欄位   【参数】
参数： 类型、 变量、 描述
多个参数 可以用多个param

@return Collection 最新3筆文章  【返回值】
参数： 类型、描述

@throws InvalidArgumentException 若提供的參數不是array型別 【方法内抛出的异常】
参数： 类型、描述

@todo 此段程式碼尚未重構，建議有時間時加以重構  【尚未完成的工作】

@since 0.1.0 11/22/15 oomusou: 新增getLatest3Posts() 【修改记录】

@deprecated 2.0之后不在支持  【未来版本停用说明】

 

变量注释

/* @var $this yii\web\View */  
比如YII2 的页面中 $this  编辑器跟不到