[TOC] ## PHP注釋規范 1. 對于引用了全局變量的函數，必須使用@glboal標記 2. 對于變量，必須用@var標記其類型(int,string,bool…) 3. 函數必須通過@param和@return標記指明其參數和返回值 4. 調用了其他函數或類的地方，要使用@link或其他標記鏈接到相應的部分，便于文檔的閱讀。 5. 必要的地方使用非文檔性注釋，提高代碼易讀性。 6. 描述性內容盡量簡明扼要，盡可能使用短語而非句子。 7. 全局變量，靜態變量和常量必須用相應標記說明 ## 注釋 ### @author 添加作者 語法 `@author [name] [<email address>] ` ### @deprecated 棄用 語法 `@deprecated [<version>] [<description>] ` ``` /** * @deprecated 3.0 棄用此方法 * @return string */ public static function invoke() { $argc="asd"; return 'Hello Guozhen'; } ``` ### @internal 只限于當前文件調用 語法:`@internal [description]`  ### @link 外部跳轉鏈接 語法`@link [URI] [<description>] ` ``` /** * <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]<, …>]) [<description>] ` ``` /** * @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] [<description>] ` | 變量類型 | 說明 | | --- | --- | | 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] [<description>] ` `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] [<description>] ` ### @throws 可能拋出的異常 語法 `@throws [Type] [<description>] ` ``` /** * @throws RuntimeException * @throws InvalidArgumentException */ ``` ### @var 變量 語法 `@var [Type] [$element_name] [<description>] ` ``` /** * @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 [描述]`