JSDoc 高级用法 #

/**
 * @virtualDoc
 * @function jQuery.ajax
 * @param {Object} options - 配置选项
 * @returns {Promise} Promise 对象
 */

/**
 * @typedef {Object} JQueryAjaxSettings
 * @property {string} [url] - 请求地址
 * @property {string} [method] - 请求方法
 * @property {Object} [data] - 请求数据
 * @property {function} [success] - 成功回调
 * @property {function} [error] - 错误回调
 */

/**
 * @external jQuery
 * @see {@link https://jquery.com|jQuery}
 */

/**
 * @function external:jQuery.ajax
 * @param {JQueryAjaxSettings} settings - 配置选项
 * @returns {JQuery.jqXHR}
 */

// 在 .d.ts 文件中
/**
 * 用户接口
 * @interface User
 */
interface User {
  /** 用户 ID */
  id: number;
  /** 用户名 */
  name: string;
}

/**
 * 获取配置
 * @param {string} key - 配置键名
 * @returns {*} 配置值
 * @example <caption>开发环境</caption>
 * // 返回开发配置
 * getConfig('apiUrl') // 'http://localhost:3000'
 * 
 * @example <caption>生产环境</caption>
 * // 返回生产配置
 * getConfig('apiUrl') // 'https://api.example.com'
 */
function getConfig(key) {
  // ...
}

/**
 * 用户认证
 * @param {Object} credentials - 凭证
 * @returns {Promise<User>}
 * 
 * @version 1.0.0
 * @example
 * // 版本 1.0
 * authenticate({ username, password })
 * 
 * @version 2.0.0
 * @example
 * // 版本 2.0 支持 OAuth
 * authenticate({ token })
 */
async function authenticate(credentials) {
  // ...
}

// @ts-check

/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 */

/**
 * 创建用户
 * @param {User} user - 用户对象
 * @returns {Promise<User>}
 */
async function createUser(user) {
  // TypeScript 会检查 user 的类型
  const response = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(user)
  });
  return response.json();
}

/**
 * @typedef {import('./types').User} User
 * @typedef {import('./types').Config} Config
 * @typedef {import('./types').ApiResponse<T>} ApiResponse
 */

/**
 * @template T
 * @param {string} endpoint
 * @param {Config} config
 * @returns {Promise<ApiResponse<T>>}
 */
async function fetchApi(endpoint, config) {
  // ...
}

/**
 * 检查是否为用户对象
 * @param {*} obj - 任意对象
 * @returns {obj is User}
 */
function isUser(obj) {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    typeof obj.id === 'number' &&
    typeof obj.name === 'string'
  );
}

/**
 * 处理数据
 * @param {User|Admin} entity - 实体
 */
function process(entity) {
  if (isUser(entity)) {
    // 这里 entity 被识别为 User 类型
    console.log(entity.name);
  }
}

/**
 * 计数器类
 * @class
 */
class Counter {
  constructor() {
    /**
     * @type {number}
     */
    this.count = 0;
  }

  /**
   * 增加计数
   * @returns {this}
   */
  increment() {
    this.count++;
    return this;
  }

  /**
   * 减少计数
   * @returns {this}
   */
  decrement() {
    this.count--;
    return this;
  }
}

// plugins/customTags.js

/**
 * @param {Object} dictionary - JSDoc 字典
 */
exports.defineTags = function(dictionary) {
  dictionary.defineTag('category', {
    mustHaveValue: true,
    onTagged: function(doclet, tag) {
      doclet.category = tag.value;
    }
  });

  dictionary.defineTag('security', {
    mustHaveValue: true,
    onTagged: function(doclet, tag) {
      doclet.security = tag.value;
    }
  });
};

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

/**
 * 删除用户
 * @category User
 * @security admin
 * @param {number} id - 用户 ID
 * @returns {Promise<void>}
 */
async function deleteUser(id) {
  // ...
}

// jsdoc.json
{
  "source": {
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  }
}

/**
 * 公开 API
 * @public
 */
function publicApi() {}

/**
 * 内部 API
 * @private
 * @ignore
 */
function internalApi() {}

// jsdoc.json
{
  "opts": {
    "access": "public"  // 只生成 public 文档
  }
}

/**
 * @module services/user
 * @description 用户服务模块
 */

/**
 * @module services/auth
 * @description 认证服务模块
 */

/**
 * @namespace API
 */

/**
 * @memberof API
 * @category User
 */
function getUser() {}

/**
 * @memberof API
 * @category User
 */
function createUser() {}

/**
 * @memberof API
 * @category Auth
 */
function login() {}

/**
 * 用户类
 * @class
 * @see {@link User#getName} 获取名称方法
 * @see {@link User#setName} 设置名称方法
 */
class User {
  /**
   * @see {@link User}
   */
  constructor() {}

  /**
   * @see module:services/user
   */
  save() {}
}

/**
 * @external Promise
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise|Promise}
 */

/**
 * @external console
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/console|console}
 */

/**
 * 记录日志
 * @param {string} message - 日志消息
 * @see {@link external:console.log}
 */
function log(message) {
  console.log(message);
}

/**
 * @see {@link module:utils/format} 格式化工具
 * @see file:./types.js 类型定义文件
 */

/**
 * 获取用户列表
 * @returns {Promise<User[]>} 用户列表 Promise
 * @async
 */
async function getUsers() {
  const response = await fetch('/api/users');
  return response.json();
}

/**
 * @async
 * @param {number} id
 * @returns {Promise<void>}
 */
async function deleteUser(id) {
  await fetch(`/api/users/${id}`, { method: 'DELETE' });
}

/**
 * 获取数据
 * @param {string} url - 请求地址
 * @param {function(?Error, *=): void} [callback] - 回调函数
 * @returns {Promise<*>|undefined} 如果没有回调则返回 Promise
 */
function fetchData(url, callback) {
  if (callback) {
    fetch(url)
      .then(res => res.json())
      .then(data => callback(null, data))
      .catch(err => callback(err));
  } else {
    return fetch(url).then(res => res.json());
  }
}

/**
 * 用户事件
 * @event User#login
 * @type {Object}
 * @property {User} user - 用户对象
 * @property {Date} timestamp - 登录时间
 */

/**
 * 用户登出事件
 * @event User#logout
 * @type {Object}
 * @property {number} userId - 用户 ID
 */

/**
 * 用户管理器
 * @class
 * @fires User#login
 * @fires User#logout
 */
class UserManager {
  /**
   * 用户登录
   * @param {Object} credentials - 凭证
   * @fires User#login
   */
  login(credentials) {
    const user = authenticate(credentials);
    
    /**
     * 登录事件
     * @event User#login
     * @type {Object}
     */
    this.emit('login', { user, timestamp: new Date() });
  }
}

/**
 * 初始化事件处理
 * @listens User#login
 * @listens User#logout
 */
function initHandlers(userManager) {
  userManager.on('login', handleLogin);
  userManager.on('logout', handleLogout);
}

/**
 * 用户状态
 * @enum {string}
 * @readonly
 */
const UserStatus = {
  /** 活跃状态 */
  ACTIVE: 'active',
  /** 未激活状态 */
  INACTIVE: 'inactive',
  /** 已禁用 */
  DISABLED: 'disabled'
};

/**
 * @param {UserStatus} status - 用户状态
 */
function updateStatus(status) {
  // ...
}

/**
 * HTTP 状态码
 * @enum {number}
 * @readonly
 */
const HttpStatus = {
  /** 成功 */
  OK: 200,
  /** 已创建 */
  CREATED: 201,
  /** 错误请求 */
  BAD_REQUEST: 400,
  /** 未授权 */
  UNAUTHORIZED: 401,
  /** 未找到 */
  NOT_FOUND: 404,
  /** 服务器错误 */
  INTERNAL_SERVER_ERROR: 500
};

/**
 * 权限枚举
 * @enum {Object}
 * @property {string} name - 权限名称
 * @property {number} level - 权限级别
 */
const Permission = {
  /** 只读权限 */
  READ: { name: 'read', level: 1 },
  /** 写入权限 */
  WRITE: { name: 'write', level: 2 },
  /** 管理权限 */
  ADMIN: { name: 'admin', level: 3 }
};

/**
 * 工具函数命名空间
 * @namespace Utils
 */

/**
 * 格式化工具
 * @namespace Utils.Format
 * @memberof Utils
 */

/**
 * 日期格式化
 * @function
 * @memberof Utils.Format
 * @param {Date} date - 日期对象
 * @returns {string}
 */
function formatDate(date) {
  // ...
}

/**
 * 数字格式化
 * @function
 * @memberof Utils.Format
 * @param {number} num - 数字
 * @returns {string}
 */
function formatNumber(num) {
  // ...
}

/**
 * 应用命名空间
 * @namespace App
 */

/**
 * 服务层
 * @namespace App.Services
 * @memberof App
 */

/**
 * 用户服务
 * @class
 * @memberof App.Services
 */
class UserService {
  // ...
}

/**
 * 数据层
 * @namespace App.Models
 * @memberof App
 */

/**
 * 用户模型
 * @class
 * @memberof App.Models
 */
class User {
  // ...
}

// jsdoc.json
{
  "opts": {
    "sourceRoot": "https://github.com/user/repo/blob/main/"
  }
}

/**
 * @source https://github.com/user/repo/blob/main/src/utils.js#L10-L20
 */
function utility() {}

/**
 * 获取用户信息
 * @description [en] Get user information
 * @description [zh] 获取用户信息
 * @description [ja] ユーザー情報を取得
 * @param {number} id - 用户 ID
 * @returns {User}
 */
function getUser(id) {}

// jsdoc.json
{
  "plugins": [
    "plugins/i18n"
  ],
  "i18n": {
    "locales": ["en", "zh", "ja"],
    "defaultLocale": "en"
  }
}

// jsdoc.json
{
  "opts": {
    "explain": true  // 输出解析的 doclet
  }
}

// jsdoc.json
{
  "opts": {
    "debug": true,
    "verbose": true
  }
}

/**
 * @debug
 */
function testFunction() {
  // 会输出该函数的 AST 结构
}

// jsdoc.json
{
  "opts": {
    "incremental": true,
    "cache": ".jsdoc-cache"
  }
}

// jsdoc.json
{
  "opts": {
    "parallel": 4  // 使用 4 个进程
  }
}

// jsdoc.json
{
  "source": {
    "exclude": [
      "node_modules",
      "dist",
      "coverage",
      "**/*.test.js",
      "**/*.spec.js"
    ]
  }
}