J*aScript文档生成_JSDoc类型注释规范_石家庄创泽智能科技有限公司

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

J*aScript文档生成_JSDoc类型注释规范

2025-11-20

浏览次数：次

返回列表

JSDoc通过标准注释提升J*aScript代码可读性与维护性，支持类型标注和工具集成。使用/* /语法，结合@param、@returns、@type等标签定义参数、返回值和变量类型，如{number}、{Array}、{string|number}；通过@typedef定义复杂对象结构，配合@type引用；支持可选参数、默认值、Promise及函数类型。在VS Code或TypeScript中启用checkJs可实现类型检查，无需迁移至TS即可获得静态类型优势，关键在于团队统一规范并结合开发工具使用。

javascript文档生成_jsdoc类型注释规范

在J*aScript开发中，良好的文档注释不仅能提升代码可读性，还能帮助团队协作和工具支持（如IDE智能提示、类型检查等）。JSDoc 是一种广泛使用的文档注释规范，通过特定的语法为函数、变量、类等添加类型和说明信息。以下是 JSDoc 类型注释的核心规范与常用实践。

基本语法结构

JSDoc 注释以 /** 开头，每行以 * 起始，使用 @param、@return、@type 等标签描述代码元素。

示例：

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

常用类型注释标签

以下是最常用的 JSDoc 标签及其用法：

@param {type} name - description：标注函数参数的类型和说明。例如：{string}、{Array<number>}</number>
@returns {type} description 或 @return：标注返回值类型
@type {type}：为变量或属性指定类型
@typedef：定义自定义类型，便于复用复杂结构
@property：用于对象类型中描述字段（常配合 @typedef 使用）
@class 或 @constructor：标识构造函数或类
@private、@public、@readonly：说明访问级别或属性状态

示例：使用 @typedef 定义对象结构

/** * @typedef {Object} User * @property {string} name - 用户名 * @property {number} age - 年龄 * @property {boolean} isActive - 是否激活 */

/* @type {User} / const user = { name: 'Alice', age: 28, isActive: true };

常见类型写法

JSDoc 支持多种类型表达方式，适配 J*aScript 的动态特性：

Docky AI

多合一AI浏览器助手，解答问题、绘制图片、阅读文档、强化搜索结果、辅助创作

100 查看详情 Docky AI

基础类型：{string}、{number}、{boolean}、{null}、{undefined}、{function}、{object}
数组：{number[]} 或 {Array<number>}</number>
联合类型：{string | number} 表示可以是字符串或数字
可选参数：@param {string} [name] - 可选的名字
默认值：@param {string} [name="John"] - 带默认值的参数
回调函数：{function(string, number): boolean} 表示接受字符串和数字，返回布尔值的函数
Promises：{Promise<string>}</string> 表示解析为字符串的 Promise