PHP注释规范

[TOC] ## PHP注释规范 1. 对于引用了全局变量的函数，必须使用@glboal标记 2. 对于变量，必须用@var标记其类型(int,string,bool…) 3. 函数必须通过@param和@return标记指明其参数和返回值 4. 调用了其他函数或类的地方，要使用@link或其他标记链接到相应的部分，便于文档的阅读。 5. 必要的地方使用非文档性注释，提高代码易读性。 6. 描述性内容尽量简明扼要，尽可能使用短语而非句子。 7. 全局变量，静态变量和常量必须用相应标记说明 ## 注释 ### @author 添加作者 语法 `@author [name] [] ` ### @deprecated 弃用 语法 `@deprecated [] [] ` ``` /** * @deprecated 3.0 弃用此方法 * @return string */ public static function invoke() { $argc="asd"; return 'Hello Guozhen'; } ``` ### @internal 只限于当前文件调用 语法:`@internal [description]`  ### @link 外部跳转链接 语法`@link [URI] [] ` ``` /** * <1>.引导外部跳转链接 * * @link https://www.baidu.com * @return string */ public static function buildBaiduUrl() { return 'https://www.baidu.com'; } ``` ### @see 跳转内部或外部链接 ``` /** * @see Email::fromString() * @see https://www.baidu.com */ ``` 与 @link 区别 | \- | @see | @link | | --- | --- | --- | | 外部链接 | √ | √ | | 内部程序 | √ | X | ### @method 声明哪些魔术方法可以调用 语法 `@method [modifier] [return type] [name]([[type] [parameter]<, …>]) [] ` ``` /** * @method int incr($number, $step = 1) 递增数字 * @method array explode(string $delimiter, string $string) 分割字符串 * @method static void incrStatic($number, $step = 1) 递增数字(静态) */ class TagMethod { function __call($name, $arguments) { } static function __callStatic($name, $arguments) { } } ``` ### @param 参数说明 语法 `@param [Type] [name] [] ` | 变量类型 | 说明 | | --- | --- | | string | 字符串 | | integer/int | number/int类型 | | boolean/bool | false/true | | float/double | number/浮点数 | | object | 对象实例 | | specifiedType | 指定类 | | mixed | 任意类型 | | array/specifiedType\[\] | 数组，可以指定成指定类型的数组 | | resource | 文件资源类型 | | void | 无返回值 | | null | \- | | callable | 可执行的回调函数 | | function | 不一定能执行的方法 | | self/$this | 当前实例 | ### @property[-(read|write)] 调用魔术方法__get/__set 语法 `@property [Type] [name] [] ` `property-read` 只读 `property-write` 只写 ``` /** * @property int $age 数字 * @property string $name 字符串 * @property mixed $any 任意类型返回值 */ class TagProperty { public function __get($name) { } public function __set($name, $value) { } } $tag = new TagProperty(); // ide 会自动提示 $tag->name; ``` ### @return 语法 `@return [Type] [] ` ### @throws 可能抛出的异常 语法 `@throws [Type] [] ` ``` /** * @throws RuntimeException * @throws InvalidArgumentException */ ``` ### @var 变量 语法 `@var [Type] [$element_name] [] ` ``` /** * @var string 年龄 */ protected string $age; /** @var string $age */ $age; ``` ### @example 记录外部保存的示例文件的位置' 语法 `@example [位置] [<起始行号> [<行数>] ] [<描述>]` ``` @example demo.php 10 3 使用示例 ``` ### @ignore 忽略相同 define ``` if ($ostest) { /** * This define will either be 'Unix' or 'Windows' */ define("OS","Unix"); } else { /** * @ignore */ define("OS","Windows"); } ``` ### @since 从什么版本开始 ``` @since 1.0.2 添加了$b参数 ``` ### @todo 语法 `@todo [描述]`