实用 JS Doc

长念阅读约 3 分钟3 年前发布2 年前编辑

© 转载需要保留原始链接，未经明确许可，禁止商业使用。支持原创 CC BY-NC-SA 4.0

JS Doc 能够结合编辑器，实现更好的语法提示。

@deprecated

标注为弃用，在使用到时会有 删除线 提示。

语法

@deprecated [<text>]

示例

/**
 * @deprecated since 2.0
 */
function getIP() {
  //...
}

@description

添加描述，别名 @desc。

语法

@description <text>
@desc <text>

示例

/**
 * @description get user client IP
 */
function getIP() {
  //...
}

@example

添加示例用法。

示例

/**
 * @example <User />
 */
export const User () => {
  //...
}

@param

指定参数类型、名称、描述，别名 @arg @argument。

语法

@param [<type>] <name> [<description>]

示例

/**
 * @param {string} name - user's name
 */
function getAge(name) {
  //...
}

@return

指定返回值类型、描述，别名 @returns。

@return [{type}] [description]

示例

/**
 * @return {string}  user's name
 */
function getName() {
  //...
}

@see

链接说明文档。

示例

/**
 * @see https://xxx.com
 */
function getName() {
  //...
}

@todo

标注待办事项。

语法

@todo text describing thing to do.

示例

/**
 * @todo correct naem to name
 */
function getUser(naem) {
  //...
}

@type

标识类型，支持引入外部类型，可以在 JS 中得到更好的语法提示。

语法

@type {typeName}

示例

/// 定义表格列
const columns = /** @type {import('choerodon-ui/pro/lib/table/Column').ColumnProps[]} */ (
  [
    //...
  ]
);

// 定义 DataSet Props
export const getDSProps = () => {
  return /** @type {import('choerodon-ui/pro/lib/data-set/DataSet').DataSetProps} */ (
    {
      //...
    }
  );
};

@typedef

描述自定义类型，可以被 @type @param 引用。

语法

@typedef [<type>] <namepath>

示例

/**
 * @typedef  {{ name: string }} User
 * @param {User} user
 */
function getUser(user) {
  //...
}