Back to Details

jsdoc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JSDoc - Quick Reference

JSDoc - 快速参考

When NOT to Use This Skill

不适用本技能的场景

  • TypeScript projects - Use the 
    jsdoc-tsdoc
    skill for TSDoc and TypeScript-specific patterns
  • JSDoc generation config - This is for writing JSDoc comments, not configuring the tool
  • Complex type systems - TypeScript provides better type checking than JSDoc annotations
  • API documentation hosting - Use documentation platforms (TypeDoc, Docusaurus, etc.)
Deep Knowledge: Use 
mcp__documentation__fetch_docs
with technology: 
jsdoc
for comprehensive tag reference, type expressions, and generation options.
  • TypeScript项目 - 针对TSDoc和TypeScript特定模式，请使用
    jsdoc-tsdoc
    技能
  • JSDoc生成配置 - 本技能用于编写JSDoc注释，而非配置工具
  • 复杂类型系统 - TypeScript提供的类型检查比JSDoc注解更完善
  • API文档托管 - 使用文档平台（TypeDoc、Docusaurus等）
深度知识：如需全面的标签参考、类型表达式和生成选项，请使用
mcp__documentation__fetch_docs
工具，指定技术为
jsdoc
。

Pattern Essenziali

核心模式

Function Documentation

函数文档

javascript
/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * const result = add(2, 3); // 5
 */
function add(a, b) {
  return a + b;
}
javascript
/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * const result = add(2, 3); // 5
 */
function add(a, b) {
  return a + b;
}

Object Types

对象类型

javascript
/**
 * @typedef {Object} User
 * @property {string} id - Unique identifier
 * @property {string} name - Full name
 * @property {string} email - Email address
 * @property {boolean} [active=true] - Optional, defaults to true
 */

/**
 * Creates a new user.
 * @param {User} userData - The user data
 * @returns {Promise<User>} The created user
 */
async function createUser(userData) {
  // ...
}
javascript
/**
 * @typedef {Object} User
 * @property {string} id - Unique identifier
 * @property {string} name - Full name
 * @property {string} email - Email address
 * @property {boolean} [active=true] - Optional, defaults to true
 */

/**
 * Creates a new user.
 * @param {User} userData - The user data
 * @returns {Promise<User>} The created user
 */
async function createUser(userData) {
  // ...
}

Class Documentation

类文档

javascript
/**
 * Represents a user in the system.
 * @class
 */
class User {
  /**
   * Creates a User instance.
   * @param {string} name - User's name
   * @param {string} email - User's email
   */
  constructor(name, email) {
    /** @type {string} */
    this.name = name;
    /** @type {string} */
    this.email = email;
  }

  /**
   * Gets the user's display name.
   * @returns {string} Display name
   */
  getDisplayName() {
    return this.name;
  }
}
javascript
/**
 * Represents a user in the system.
 * @class
 */
class User {
  /**
   * Creates a User instance.
   * @param {string} name - User's name
   * @param {string} email - User's email
   */
  constructor(name, email) {
    /** @type {string} */
    this.name = name;
    /** @type {string} */
    this.email = email;
  }

  /**
   * Gets the user's display name.
   * @returns {string} Display name
   */
  getDisplayName() {
    return this.name;
  }
}

Callback Types

回调类型

javascript
/**
 * @callback FetchCallback
 * @param {Error|null} error - Error if failed
 * @param {Object} data - Response data
 */

/**
 * Fetches data from the API.
 * @param {string} url - The URL to fetch
 * @param {FetchCallback} callback - Called with the result
 */
function fetchData(url, callback) {
  // ...
}
javascript
/**
 * @callback FetchCallback
 * @param {Error|null} error - Error if failed
 * @param {Object} data - Response data
 */

/**
 * Fetches data from the API.
 * @param {string} url - The URL to fetch
 * @param {FetchCallback} callback - Called with the result
 */
function fetchData(url, callback) {
  // ...
}

Generic Types

泛型类型

javascript
/**
 * @template T
 * @param {T[]} array - Array of items
 * @returns {T|undefined} First item or undefined
 */
function first(array) {
  return array[0];
}
javascript
/**
 * @template T
 * @param {T[]} array - Array of items
 * @returns {T|undefined} First item or undefined
 */
function first(array) {
  return array[0];
}

Module Documentation

模块文档

javascript
/**
 * @module utils/string
 * @description String utility functions
 */

/**
 * Capitalizes the first letter.
 * @param {string} str - Input string
 * @returns {string} Capitalized string
 */
export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}
javascript
/**
 * @module utils/string
 * @description String utility functions
 */

/**
 * Capitalizes the first letter.
 * @param {string} str - Input string
 * @returns {string} Capitalized string
 */
export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

Anti-Patterns

反模式

Anti-PatternWhy It's WrongCorrect Approach
No documentation at allNo IDE hints, hard to use APIDocument at least public functions and complex logic
Copying implementation as commentAdds no value, becomes outdatedDescribe behavior, not implementation
Missing 
@param
types		No type checking or autocompleteAlways specify parameter types
Outdated documentationMisleading, worse than noneUpdate docs when changing code
Over-documenting obvious codeClutters code, maintenance burdenDocument complex logic, skip trivial getters/setters
Using wrong tag for purposeConfuses tools, incorrect typesUse 
@typedef
for types, 
@callback
for functions
Not importing typesBroken type referencesUse 
@typedef {import('./types').Type}
Duplicate type info in TypeScriptRedundant, desynchronizesLet TypeScript types speak for themselves
反模式问题所在正确做法
完全不写文档无IDE提示，API难以使用至少对公共函数和复杂逻辑编写文档
复制实现代码作为注释无实际价值，易过时描述行为而非实现细节
缺少
@param
类型		无类型检查或自动补全始终指定参数类型
文档过时误导使用者，比无文档更糟修改代码时同步更新文档
过度注释明显代码使代码杂乱，增加维护负担仅注释复杂逻辑，跳过琐碎的getter/setter
使用错误标签混淆工具，导致类型错误使用
@typedef
定义类型，
@callback
定义函数
未导入类型类型引用失效使用
@typedef {import('./types').Type}
在TypeScript中重复类型信息冗余，易不同步让TypeScript类型自行说明

Quick Troubleshooting

快速故障排查

IssueDiagnosisSolution
IDE not showing type hintsJSDoc comments malformed or incompleteEnsure 
@param {Type}
and 
@returns {Type}
are present
Type errors in VS CodeIncorrect JSDoc type syntaxUse TypeScript-style types: 
{string|null}
not 
{?string}
Broken type importsWrong import path in 
@typedef
Use 
@typedef {import('./file').TypeName}
with correct path
Generic types not workingImproper 
@template
usage		Declare 
@template T
before using it in params
Documentation not generatedJSDoc tool not configuredRun 
jsdoc -c jsdoc.json
with proper config
Optional params showing as requiredMissing 
[]
in param name		Use 
@param {string} [optional]
or 
{string=}
Types not recognizedTypo or undeclared typedefDefine types with 
@typedef
before use
Return type ignoredMissing 
@returns
tag		Always document return value with 
@returns {Type}
问题诊断解决方案
IDE不显示类型提示JSDoc注释格式错误或不完整确保存在
@param {Type}
和
@returns {Type}
标签
VS Code中出现类型错误JSDoc类型语法不正确使用TypeScript风格的类型：
{string|null}
而非
{?string}
类型导入失效
@typedef
中的导入路径错误		使用
@typedef {import('./file').TypeName}
并确保路径正确
泛型类型无法正常工作
@template
使用不当		在参数前声明
@template T
文档未生成JSDoc工具未配置使用正确配置运行
jsdoc -c jsdoc.json
可选参数显示为必填参数名称缺少
[]
使用
@param {string} [optional]
或
{string=}
类型不被识别拼写错误或未声明类型定义使用
@typedef
提前定义类型
返回类型被忽略缺少
@returns
标签		始终使用
@returns {Type}
记录返回值

Related Skills

相关技能

  • TSDoc/JSDoc
  • TypeScript
  • TSDoc/JSDoc
  • TypeScript