目录
JSDoc 简介
JSDoc 是一种用于 JavaScript 的文档生成工具，通过在代码中添加特定格式的注释，自动生成 API 文档。以下是一个简单的简介示例：
/**
* 一个简单的问候函数。
* @param {string} name - 用户姓名
* @returns {string} 问候语
*/
function sayHello(name) {
return `Hello, ${name}!`;
}
基本语法
JSDoc 注释以 /** 开头，以 */ 结尾，通常用于描述函数、类、变量等代码元素。以下是多个示例，展示基本语法的不同应用场景。
示例 1：为简单函数添加注释
/**
* 计算两数之和。
* @param {number} x - 第一个数
* @param {number} y - 第二个数
* @returns {number} 两数之和
*/
function sum(x, y) {
return x + y;
}
示例 2：为具有默认参数的函数添加注释
/**
* 生成问候语。
* @param {string} name - 用户姓名
* @param {string} [greeting="Hello"] - 问候词，默认为 "Hello"
* @returns {string} 完整的问候语
*/
function greet(name, greeting = "Hello") {
return `${greeting}, ${name}!`;
}
示例 3：为类添加注释
/**
* 表示一个矩形。
* @class
*/
class Rectangle {
/**
* 创建一个矩形。
* @param {number} width - 宽度
* @param {number} height - 高度
*/
constructor(width, height) {
this.width = width;
this.height = height;
}
/**
* 计算矩形面积。
* @returns {number} 面积
*/
getArea() {
return this.width * this.height;
}
}
示例 4：为变量添加注释
/**
* 当前用户的详细信息。
* @type {Object}
* @property {string} username - 用户名
* @property {number} id - 用户ID
*/
const currentUser = {
username: "Alice",
id: 123,
};
示例 5：为常量添加注释
/**
* 应用程序的最大连接数。
* @type {number}
*/
const MAX_CONNECTIONS = 100;
最新特性
JSDoc 4.0.4 引入了对 ES6+ 语法、改进的类型系统和新增标签的支持。以下是每个特性的详细示例。
1. 对 ES6+ 语法的支持
JSDoc 4.0.4 更好地支持现代 JavaScript 特性，如箭头函数、解构赋值和模块。
示例 1：箭头函数
/**
* 将数字乘以 3。
* @param {number} value - 输入值
* @returns {number} 三倍值
*/
const triple = (value) => value * 3;
示例 2：解构赋值参数
/**
* 打印书籍信息。
* @param {Object} book - 书籍对象
* @param {string} book.title - 书籍标题
* @param {number} book.year - 出版年份
*/
function printBook({ title, year }) {
console.log(`${title} was published in ${year}`);
}
示例 3：ES6 模块导出
/**
* 计算两数之积。
* @param {number} a - 第一个数
* @param {number} b - 第二个数
* @returns {number} 乘积
*/
export function multiply(a, b) {
return a * b;
}
2. 改进的类型系统
支持联合类型、交叉类型和泛型等高级类型。
示例 1：联合类型
/**
* 检查值是否为有效输入。
* @param {string | number} input - 输入值，可以是字符串或数字
* @returns {boolean} 是否有效
*/
function validateInput(input) {
return input !== null && input !== undefined;
}
示例 2：交叉类型
/**
* @typedef {Object} Position
* @property {number} x - X 坐标
* @property {number} y - Y 坐标
*/
/**
* @typedef {Object} Color
* @property {string} color - 颜色值
*/
/**
* 表示一个有颜色和位置的点。
* @type {Position & Color}
*/
const coloredPoint = {
x: 10,
y: 20,
color: "red",
};
示例 3：泛型
/**
* 一个通用的容器类。
* @template T
*/
class Container {
/**
* @param {T} item - 容器中的项
*/
constructor(item) {
this.item = item;
}
/**
* 获取容器中的项。
* @returns {T} 容器中的项
*/
getItem() {
return this.item;
}
}
// 使用示例
const stringContainer = new Container("Hello");
const numberContainer = new Container(42);
3. 新的标签
新增 @async 和 @generator 等标签。
示例 1：异步函数
/**
* 从服务器获取用户数据。
* @async
* @param {string} userId - 用户ID
* @returns {Promise<Object>} 用户数据
*/
async function fetchUser(userId) {
const response = await fetch(`/api/users/${userId}`);
return response.json();
}
示例 2：生成器函数
/**
* 生成斐波那契数列。
* @generator
* @yields {number} 下一个斐波那契数
*/
function* fibonacci() {
let a = 0,
b = 1;
while (true) {
yield a;
[a, b] = [b, a + b];
}
}
标签详解
以下是常用 JSDoc 标签的详细说明及其示例。
@param
描述函数参数。
示例 1：基本用法
/**
* 合并两个字符串。
* @param {string} str1 - 第一个字符串
* @param {string} str2 - 第二个字符串
* @returns {string} 合并后的字符串
*/
function concat(str1, str2) {
return str1 + str2;
}
示例 2：可选参数
/**
* 创建用户简介。
* @param {string} name - 用户姓名
* @param {number} [age] - 用户年龄（可选）
* @returns {string} 简介
*/
function createProfile(name, age) {
return age ? `${name}, ${age} years old` : name;
}
@returns
描述函数返回值。
示例 1：基本用法
/**
* 获取当前时间戳。
* @returns {number} 当前时间戳（毫秒）
*/
function getTimestamp() {
return Date.now();
}
示例 2：复杂返回值
/**
* 获取用户详细信息。
* @returns {{id: number, name: string}} 用户对象
*/
function getUserDetails() {
return { id: 1, name: "Bob" };
}
@type
指定变量或属性的类型。
示例 1：简单 基本类型
/**
* 用户的年龄。
* @type {number}
*/
let userAge = 25;
示例 2：复杂类型
/**
* 坐标点。
* @type {{x: number, y: number}}
*/
const point = { x: 10, y: 20 };
@class
标记一个类。
示例
/**
* 表示一辆汽车。
* @class
*/
class Car {
/**
* @param {string} model - 汽车型号
*/
constructor(model) {
this.model = model;
}
}
@module
标记一个模块。
示例
/**
* @module stringUtils
*/
/**
* 反转字符串。
* @param {string} str - 输入字符串
* @returns {string} 反转后的字符串
*/
function reverse(str) {
return str.split("").reverse().join("");
}
@typedef
定义自定义类型。
示例 1：简单类型
/**
* @typedef {Object} Address
* @property {string} city - 城市
* @property {string} country - 国家
*/
/**
* @type {Address}
*/
const home = { city: "Beijing", country: "China" };
示例 2：嵌套类型
/**
* @typedef {Object} Employee
* @property {string} name - 员工姓名
* @property {Address} address - 员工地址
*/
/**
* @type {Employee}
*/
const employee = {
name: "Tom",
address: { city: "Shanghai", country: "China" },
};
@property
描述对象属性。
示例
/**
* 应用程序设置。
* @type {Object}
* @property {boolean} debug - 是否启用调试模式
* @property {string} env - 运行环境
*/
const settings = {
debug: true,
env: "development",
};
@example
提供使用示例。
示例
/**
* 将字符串转换为大写。
* @param {string} text - 输入文本
* @returns {string} 大写文本
* @example
* const result = toUpper("hello"); // result is "HELLO"
*/
function toUpper(text) {
return text.toUpperCase();
}
@throws
描述可能抛出的异常。
示例
/**
* 除以一个数字。
* @param {number} a - 被除数 <query>尽可能多的对所有的知识点进行举例</query>
* @param {number} b - 除数
* @returns {number} 商
* @throws {Error} 如果 b 为 0
*/
function divide(a, b) {
if (b === 0) throw new Error("Division by zero");
return a / b;
}
@see
提供相关参考链接。
示例
/**
* 计算平方根。
* @param {number} n - 输入值
* @returns {number} 平方根
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt}
*/
function sqrt(n) {
return Math.sqrt(n);
}
最佳实践
以下是编写高质量 JSDoc 的建议及其示例。
1. 保持一致性
示例
/**
* 获取用户名。
* @param {string} id - 用户ID
* @returns {string} 用户名
*/
function getUsername(id) {
return `user_${id}`;
}
/**
* 获取用户邮箱。
* @param {string} id - 用户ID
* @returns {string} 邮箱
*/
function getEmail(id) {
return `user${id}@example.com`;
}
2. 简洁明了
示例
/**
* 检查数字是否为偶数。
* @param {number} num - 输入数字
* @returns {boolean} 是否为偶数
*/
function isEven(num) {
return num % 2 === 0;
}
3. 及时更新
示例（更新前）
/**
* 加 1。
* @param {number} x - 输入值
* @returns {number} x + 1
*/
function increment(x) {
return x + 1;
}
示例（更新后）
/**
* 加指定值。
* @param {number} x - 输入值
* @param {number} [step=1] - 增量，默认为 1
* @returns {number} x + step
*/
function increment(x, step = 1) {
return x + step;
}
4. 使用类型
示例
/**
* @typedef {Object} Product
* @property {string} name - 产品名称
* @property {number} price - 产品价格
*/
/**
* 获取产品信息。
* @param {string} id - 产品ID
* @returns {Product} 产品对象
*/
function getProduct(id) {
return { name: `Product ${id}`, price: 100 };
}
5. 提供示例代码
示例
/**
* 过滤数组中的奇数。
* @param {number[]} numbers - 输入数组
* @returns {number[]} 奇数数组
* @example
* const odds = filterOdds([1, 2, 3, 4, 5]); // odds is [1, 3, 5]
*/
function filterOdds(numbers) {
return numbers.filter((n) => n % 2 !== 0);
}
参考资料
通过以上大量示例，本指南涵盖了 JSDoc 的基本语法、最新特性、标签详解和最佳实践的每个知识点。希望这些示例能帮助你全面掌握 JSDoc 的用法，并在项目中编写出高质量的文档！