JSDoc 基础语法 #

/**
 * 这是一个 JSDoc 注释块
 * 可以跨越多行
 * 每行通常以星号开头
 */

// 这是单行注释，不会被 JSDoc 解析

/*
 * 这是多行注释
 * 也不会被 JSDoc 解析
 */

/**
 * 这是 JSDoc 注释
 * 以 /** 开始（两个星号）
 * 会被 JSDoc 解析生成文档
 */

/**
 * 计算两数之和
 */
function add(a, b) {
  return a + b;
}

/**
 * 用户名称
 */
const userName = 'John';

/**
 * 配置对象
 */
const config = {
  /**
   * API 基础地址
   */
  baseURL: '/api',
  
  /**
   * 请求超时时间
   */
  timeout: 5000
};

/**
 * 计算两个数字的和
 */
function add(a, b) {
  return a + b;
}

/**
 * 计算两个数字的和
 * 
 * 该函数接受两个数字参数，返回它们的和。
 * 支持整数和浮点数运算。
 * 
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两数之和
 */
function add(a, b) {
  return a + b;
}

/**
 * 格式化日期
 * 
 * 将日期对象格式化为指定格式的字符串。
 * 
 * 支持的格式：
 * - `YYYY` - 四位年份
 * - `MM` - 两位月份
 * - `DD` - 两位日期
 * 
 * @param {Date} date - 日期对象
 * @param {string} format - 格式字符串
 * @returns {string} 格式化后的日期字符串
 * 
 * @example
 * // 返回 '2024-01-15'
 * formatDate(new Date(2024, 0, 15), 'YYYY-MM-DD')
 */
function formatDate(date, format) {
  // ...
}

/**
 * @param {类型} 参数名 - 描述
 */

// 基本用法
/**
 * @param {string} name - 用户名
 */
function greet(name) {
  return `Hello, ${name}`;
}

// 带默认值的参数
/**
 * @param {string} [name='Guest'] - 用户名，默认为 'Guest'
 */
function greet(name = 'Guest') {
  return `Hello, ${name}`;
}

// 可选参数
/**
 * @param {string} name - 用户名
 * @param {number} [age] - 年龄（可选）
 */
function createUser(name, age) {
  // ...
}

// 对象参数的属性
/**
 * @param {Object} user - 用户对象
 * @param {string} user.name - 用户名
 * @param {number} user.age - 年龄
 * @param {string} [user.email] - 邮箱（可选）
 */
function saveUser(user) {
  // ...
}

// 解构参数
/**
 * @param {Object} options - 配置选项
 * @param {string} options.url - 请求地址
 * @param {string} [options.method='GET'] - 请求方法
 * @param {Object} [options.headers] - 请求头
 */
function request({ url, method = 'GET', headers }) {
  // ...
}

/**
 * @returns {类型} 描述
 */

// 基本用法
/**
 * @returns {number} 两数之和
 */
function add(a, b) {
  return a + b;
}

// 返回对象
/**
 * @returns {Object} 用户信息对象
 * @returns {string} return.name - 用户名
 * @returns {number} return.age - 年龄
 */
function getUser() {
  return { name: 'John', age: 25 };
}

// 返回 Promise
/**
 * @returns {Promise<User>} 用户 Promise
 */
async function fetchUser() {
  // ...
}

// 无返回值
/**
 * @returns {void}
 */
function log(message) {
  console.log(message);
}

/**
 * @throws {类型} 描述
 */

// 单个异常
/**
 * @throws {Error} 当除数为零时抛出
 */
function divide(a, b) {
  if (b === 0) {
    throw new Error('Division by zero');
  }
  return a / b;
}

// 多个异常
/**
 * @throws {TypeError} 当参数类型错误时抛出
 * @throws {RangeError} 当参数超出范围时抛出
 */
function setAge(age) {
  if (typeof age !== 'number') {
    throw new TypeError('Age must be a number');
  }
  if (age < 0 || age > 150) {
    throw new RangeError('Age must be between 0 and 150');
  }
}

/**
 * 计算两数之和
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两数之和
 * @example
 * // 基本用法
 * add(1, 2) // 返回 3
 * 
 * @example
 * // 使用变量
 * const x = 10
 * const y = 20
 * add(x, y) // 返回 30
 */
function add(a, b) {
  return a + b;
}

// 多个示例
/**
 * 格式化字符串
 * @param {string} template - 模板字符串
 * @param {Object} data - 数据对象
 * @returns {string} 格式化后的字符串
 * @example
 * // 简单替换
 * format('Hello, {name}!', { name: 'John' })
 * // 返回 'Hello, John!'
 * 
 * @example
 * // 多个占位符
 * format('{greeting}, {name}!', { greeting: 'Hi', name: 'Jane' })
 * // 返回 'Hi, Jane!'
 */
function format(template, data) {
  // ...
}

/**
 * @deprecated 该方法已废弃，请使用 newMethod
 * @see newMethod
 */
function oldMethod() {
  // ...
}

/**
 * @deprecated 自版本 2.0 起废弃
 * @see {@link newMethod}
 */
function anotherOldMethod() {
  // ...
}

/**
 * @see 相关文档或代码
 */

/**
 * 发送 HTTP 请求
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch API}
 * @see request
 */
function fetch(url) {
  // ...
}

/**
 * 用户类
 * @see User
 * @see Admin
 */
class BaseUser {
  // ...
}

/**
 * 用户类
 * @class
 * @see {@link User} 用户类
 * @see {@link User#getName} 获取名称方法
 * @see {@link module:utils/format} 格式化工具
 */
class User {
  // ...
}

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

/**
 * @type {number}
 */
const age = 25;

/**
 * @type {string[]}
 */
const tags = ['js', 'node', 'react'];

/**
 * @type {Object<string, number>}
 */
const scores = { math: 90, english: 85 };

/**
 * @type {User | null}
 */
let currentUser = null;

/**
 * API 基础地址
 * @const {string}
 */
const API_BASE_URL = 'https://api.example.com';

/**
 * 配置对象
 * @const {Object}
 */
const CONFIG = {
  timeout: 5000,
  retries: 3
};

/**
 * 用户 ID
 * @type {string}
 * @readonly
 */
this.id = generateId();

/**
 * 计算数组元素的总和
 * @param {number[]} numbers - 数字数组
 * @returns {number} 总和
 */
function sum(numbers) {
  return numbers.reduce((acc, num) => acc + num, 0);
}

/**
 * 双倍数值
 * @param {number} value - 输入值
 * @returns {number} 双倍后的值
 */
const double = (value) => value * 2;

class Calculator {
  /**
   * 加法运算
   * @param {number} a - 第一个数字
   * @param {number} b - 第二个数字
   * @returns {number} 两数之和
   */
  add(a, b) {
    return a + b;
  }

  /**
   * 减法运算
   * @instance
   * @memberof Calculator
   * @param {number} a - 被减数
   * @param {number} b - 减数
   * @returns {number} 差
   */
  subtract(a, b) {
    return a - b;
  }
}

class User {
  /**
   * 创建用户实例
   * @static
   * @param {Object} data - 用户数据
   * @returns {User} 用户实例
   */
  static create(data) {
    return new User(data);
  }
}

/**
 * 用户类
 * @class
 * @classdesc 表示系统中的用户
 * 
 * @example
 * const user = new User('John', 'john@example.com');
 * user.getName(); // 'John'
 */
class User {
  /**
   * 创建用户实例
   * @param {string} name - 用户名
   * @param {string} email - 邮箱地址
   */
  constructor(name, email) {
    /**
     * 用户名
     * @type {string}
     */
    this.name = name;
    
    /**
     * 邮箱地址
     * @type {string}
     */
    this.email = email;
  }

  /**
   * 获取用户名
   * @returns {string} 用户名
   */
  getName() {
    return this.name;
  }
}

class Config {
  /**
   * 默认超时时间
   * @type {number}
   * @static
   */
  static DEFAULT_TIMEOUT = 5000;

  /**
   * 配置名称
   * @type {string}
   */
  name = 'default';
}

/**
 * 管理员用户
 * @class
 * @extends User
 */
class Admin extends User {
  /**
   * 创建管理员实例
   * @param {string} name - 用户名
   * @param {string} email - 邮箱地址
   * @param {string[]} permissions - 权限列表
   */
  constructor(name, email, permissions) {
    super(name, email);
    /**
     * 权限列表
     * @type {string[]}
     */
    this.permissions = permissions;
  }
}

/**
 * HTTP 请求工具模块
 * @module utils/http
 */

/**
 * 发送 GET 请求
 * @param {string} url - 请求地址
 * @returns {Promise<Response>} 响应 Promise
 */
export function get(url) {
  return fetch(url);
}

/**
 * 发送 POST 请求
 * @param {string} url - 请求地址
 * @param {Object} data - 请求数据
 * @returns {Promise<Response>} 响应 Promise
 */
export function post(url, data) {
  return fetch(url, {
    method: 'POST',
    body: JSON.stringify(data)
  });
}

/**
 * @module UserService
 */

/**
 * 获取用户列表
 * @function
 * @returns {Promise<User[]>} 用户列表 Promise
 */
export const getUsers = async () => {
  // ...
};

/**
 * 用户类
 * @class
 */
export class User {
  // ...
}

/**
 * @module api
 */

/**
 * @typedef {import('./types').User} User
 * @typedef {import('./types').ApiResponse} ApiResponse
 */

/**
 * 获取用户信息
 * @param {number} id - 用户 ID
 * @returns {Promise<ApiResponse<User>>}
 */
export async function getUser(id) {
  // ...
}

// ✅ 好的描述
/**
 * 格式化日期为指定格式的字符串
 * @param {Date} date - 要格式化的日期对象
 * @param {string} format - 格式字符串，如 'YYYY-MM-DD'
 * @returns {string} 格式化后的日期字符串
 */
function formatDate(date, format) {
  // ...
}

// ❌ 不好的描述
/**
 * 格式化日期
 */
function formatDate(date, format) {
  // ...
}

// ✅ 注释与代码同步
/**
 * 创建用户
 * @param {string} name - 用户名
 * @param {string} email - 邮箱地址
 * @param {number} [age] - 年龄（可选）
 * @returns {User} 用户实例
 */
function createUser(name, email, age) {
  // ...
}

// ❌ 注释与代码不同步
/**
 * 创建用户
 * @param {string} name - 用户名
 * @param {string} email - 邮箱地址
 */
function createUser(name, email, age, phone) {
  // ...
}

// ✅ 正确的类型
/**
 * @param {string[]} names - 名称数组
 * @returns {Object<string, number>} 键值对对象
 */

// ❌ 模糊的类型
/**
 * @param {Array} names - 数组
 * @returns {Object} 对象
 */

// ✅ 有意义的示例
/**
 * 计算折扣价格
 * @param {number} price - 原价
 * @param {number} discount - 折扣率（0-1）
 * @returns {number} 折扣后价格
 * @example
 * // 计算 100 元打 8 折
 * calculateDiscount(100, 0.8) // 返回 80
 * 
 * @example
 * // 计算 50 元打 9 折
 * calculateDiscount(50, 0.9) // 返回 45
 */
function calculateDiscount(price, discount) {
  return price * discount;
}

// ❌ 无意义的示例
/**
 * @example
 * calculateDiscount(100, 0.8)
 */