PHPDoc、JSDoc、Vue JSDoc相关的语法
- 工作笔记
- 2023-08-30
- 1130热度
- 1评论
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 填入.
*/