PHPDoc

PHPDoc 是一種注釋規(guī)范，用于為 PHP 代碼提供文檔。

1.@param

@param參數(shù)類型 $參數(shù)名稱 參數(shù)說(shuō)明 - 用于指定一個(gè)函數(shù)或方法的參數(shù)類型、名稱和說(shuō)明。

/**
 * 計(jì)算兩個(gè)數(shù)的和
 * @param int $a 第一個(gè)數(shù)字
 * @param int $b 第二個(gè)數(shù)字
 * @return int 兩數(shù)之和
 */
function add($a, $b){
    return $a + $b;
}

2.@return

@return 返回值類型 返回值說(shuō)明 - 用于指定一個(gè)函數(shù)或方法返回值的類型和說(shuō)明。

/**
 * 計(jì)算平均值
 * @param array $numbers 數(shù)字?jǐn)?shù)組
 * @return float 平均數(shù)
 */
function average($numbers){
    return array_sum($numbers)/count($numbers);
}

3.@var

@var 變量類型 - 用于指定變量的數(shù)據(jù)類型。

/**
 * 用戶姓名
 *
 * @var string
 */
public $name;

4.@throws

@throws 異常類型 異常說(shuō)明，用于指定方法或函數(shù)所可能拋出的異常。

/**
* 根據(jù)用戶名查找用戶信息
* param string $username 用戶名.
* return string 用戶信息.
* throws InvalidUsernameException 如果用戶名無(wú)效，則拋出異常.
*/
function getUserInfoByUsername($username) {
   if (/* 檢查用戶名是否有效*/) {
      // 如果用戶名無(wú)效，則拋出異常.
      throw new InvalidUsernameException('Invalid username provided '.$username);
   }
 
   // 返回用戶信息.
   return $userInfo;
}

5.@deprecated

@deprecated 已棄用的方法或函數(shù) ，用于標(biāo)記方法或函數(shù)已經(jīng)過(guò)時(shí)不推薦使用。

/**
 * 棄用的方法
 * @deprecated 該方法已被棄用，請(qǐng)改用 newMethod 函數(shù)。
 */
function OldMethod(){
    // 該方法已被棄用
}

JSDoc

JSDoc 是一種用于為 JavaScript 代碼提供文檔的注釋規(guī)范。

1.@param

@param 參數(shù)名 {類型} 參數(shù)描述 - 用于指定一個(gè)函數(shù)或方法的參數(shù)名、數(shù)據(jù)類型和說(shuō)明。

/**
 * 計(jì)算兩個(gè)數(shù)字之和。
 * @param {number} a - 第一個(gè)數(shù)字
 * @param {number} b - 第二個(gè)數(shù)字
 * @returns {number} 兩個(gè)數(shù)字之和
 */
function add(a, b) {
    return a + b;
}

2.@returns

@returns {類型} 返回值描述 - 用于指定一個(gè)函數(shù)或方法返回值的類型和說(shuō)明。

/**
 * 計(jì)算數(shù)組中所有元素之和。
 *
 * @param {Array<number>} arr - 數(shù)字?jǐn)?shù)組
 * @returns {number} 數(shù)組中所有元素之和
 */
function sum(arr) {
    return arr.reduce((acc, cur) => acc + cur);
}

3.@typedef

@typedef 類型定義名稱 = 類型定義內(nèi)容 - 用于定義一個(gè)自定義數(shù)據(jù)類型，可以在函數(shù)注釋或其它地方引用它，并且可以包含屬性、方法等成員。

/**
 * 用戶信息對(duì)象。
 *
 * @typedef {Object} UserInfo
 *
 * @property {string} name 用戶姓名
 * @property {string} email 用戶郵箱地址
 */

/**
* 獲取用戶信息.
*
* @param userId 用戶ID.
*
* returns {UserInfo[]} 所有匹配用戶的列表.
*/
function getUserInfo(userId) {
   // 查詢并返回用戶信息...
}

4.@type

@type，進(jìn)行基本類型注釋。

// TypeScript
let name: string = 'Amy';

// JSDoc
/** @type {string} */
let name = 'Amy';

Vue JsDoc

Vue.js 的文檔注釋使用的是基于 JSDoc 的風(fēng)格，但是添加了Vue.js 特有的運(yùn)行時(shí)和模板相關(guān)的標(biāo)簽。

1.@prop  

@prop {type} propName - 用于描述組件的屬性列表（props），其中 type 是指屬性數(shù)據(jù)類型，propName 是指屬性名稱。

/**
 * Button 組件
 *
 * @prop {Boolean} disabled 是否禁用
 * @prop {String} type button 類型（按鈕類型），可選值為 `'primary'`, `'success'`, `'warning'`, `'danger'`, 或者不設(shè)置.
 */

2.@event

@event {eventName} - 用于描述組件所觸發(fā)的事件（events）及其參數(shù)。

/**
 * Table 組件.
 *
 * @event row-clicked({row: Object}) 表格行被點(diǎn)擊時(shí)觸發(fā).
 */

3.@slot

/**
 * Alert 組件.
 *
 * @slot title 標(biāo)題
 *   Alert 標(biāo)題內(nèi)容.
 *
 * @slot content 內(nèi)容
 *   Alert 描述信息，支持 HTML 填入.
 */