PHPDoc、JSDoc、Vue JSDoc相关的语法，持续记录

PHPDoc

PHPDoc 是一种注释规范，用于为 PHP 代码提供文档。

1.@param

@param参数类型 $参数名称 参数说明 - 用于指定一个函数或方法的参数类型、名称和说明。

/**
 * 计算两个数的和
 * @param int $a 第一个数字
 * @param int $b 第二个数字
 * @return int 两数之和
 */
function add($a, $b){
    return $a + $b;
}

2.@return

@return 返回值类型 返回值说明 - 用于指定一个函数或方法返回值的类型和说明。

/**
 * 计算平均值
 * @param array $numbers 数字数组
 * @return float 平均数
 */
function average($numbers){
    return array_sum($numbers)/count($numbers);
}

3.@var

@var 变量类型 - 用于指定变量的数据类型。

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

4.@throws

@throws 异常类型 异常说明，用于指定方法或函数所可能抛出的异常。

/**
* 根据用户名查找用户信息
* param string $username 用户名.
* return string 用户信息.
* throws InvalidUsernameException 如果用户名无效，则抛出异常.
*/
function getUserInfoByUsername($username) {
   if (/* 检查用户名是否有效*/) {
      // 如果用户名无效，则抛出异常.
      throw new InvalidUsernameException('Invalid username provided '.$username);
   }
 
   // 返回用户信息.
   return $userInfo;
}

5.@deprecated

@deprecated 已弃用的方法或函数 ，用于标记方法或函数已经过时不推荐使用。

/**
 * 弃用的方法
 * @deprecated 该方法已被弃用，请改用 newMethod 函数。
 */
function OldMethod(){
    // 该方法已被弃用
}

JSDoc

JSDoc 是一种用于为 JavaScript 代码提供文档的注释规范。

1.@param

@param 参数名 {类型} 参数描述 - 用于指定一个函数或方法的参数名、数据类型和说明。

/**
 * 计算两个数字之和。
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两个数字之和
 */
function add(a, b) {
    return a + b;
}

2.@returns

@returns {类型} 返回值描述 - 用于指定一个函数或方法返回值的类型和说明。

/**
 * 计算数组中所有元素之和。
 *
 * @param {Array<number>} arr - 数字数组
 * @returns {number} 数组中所有元素之和
 */
function sum(arr) {
    return arr.reduce((acc, cur) => acc + cur);
}

3.@typedef

@typedef 类型定义名称 = 类型定义内容 - 用于定义一个自定义数据类型，可以在函数注释或其它地方引用它，并且可以包含属性、方法等成员。

/**
 * 用户信息对象。
 *
 * @typedef {Object} UserInfo
 *
 * @property {string} name 用户姓名
 * @property {string} email 用户邮箱地址
 */

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

4.@type

@type，进行基本类型注释。

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

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

Vue JsDoc

Vue.js 的文档注释使用的是基于 JSDoc 的风格，但是添加了Vue.js 特有的运行时和模板相关的标签。

1.@prop  

@prop {type} propName - 用于描述组件的属性列表（props），其中 type 是指属性数据类型，propName 是指属性名称。

/**
 * Button 组件
 *
 * @prop {Boolean} disabled 是否禁用
 * @prop {String} type button 类型（按钮类型），可选值为 `'primary'`, `'success'`, `'warning'`, `'danger'`, 或者不设置.
 */

2.@event

@event {eventName} - 用于描述组件所触发的事件（events）及其参数。

/**
 * Table 组件.
 *
 * @event row-clicked({row: Object}) 表格行被点击时触发.
 */

3.@slot

/**
 * Alert 组件.
 *
 * @slot title 标题
 *   Alert 标题内容.
 *
 * @slot content 内容
 *   Alert 描述信息，支持 HTML 填入.
 */