jsdoc

JSDoc - クイックリファレンス

このスキルを使用しない場合

• TypeScript プロジェクト - TSDoc および TypeScript 固有のパターンには、jsdoc-tsdoc スキルを使用してください
• JSDoc 生成設定 - これは JSDoc コメントの記述用であり、ツールの設定用ではありません
• 複雑な型システム - JSDoc アノテーションよりも、TypeScript のほうが優れた型チェックを提供します
• API ドキュメントのホスティング - ドキュメントプラットフォーム（TypeDoc、Docusaurus など）を使用してください

詳細な知識：包括的なタグリファレンス、型式、生成オプションについては、technology: jsdoc を指定して mcp__documentation__fetch_docs を使用してください。

基本的なパターン

関数のドキュメント

/**
 * 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;
}

オブジェクトの型

/**
 * @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) {
  // ...
}

クラスのドキュメント

/**
 * 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 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) {
  // ...
}

ジェネリック型

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

モジュールのドキュメント

/**
 * @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);
}

アンチパターン

アンチパターン	問題点	正しい方法
ドキュメントがまったくない	IDE のヒントがなく、API を使いにくい	少なくとも公開関数と複雑なロジックをドキュメント化する
実装をコメントとしてコピーする	価値がなく、古くなる	実装ではなく動作を説明する
@param の型がない	型チェックや自動補完ができない	常にパラメーターの型を指定する
ドキュメントが古い	誤解を招き、ない場合より悪い	コードを変更したらドキュメントも更新する
明白なコードを過剰にドキュメント化する	コードが煩雑になり、保守の負担が増える	複雑なロジックをドキュメント化し、単純なゲッター／セッターは省略する
用途に合わないタグを使う	ツールを混乱させ、型が不正になる	型には @typedef、関数には @callback を使用する
型をインポートしない	型参照が壊れる	@typedef {import('./types').Type} を使用する
TypeScript で型情報を重複させる	冗長になり、同期が取れなくなる	TypeScript の型に任せる

トラブルシューティング

問題	原因	解決策
IDE に型ヒントが表示されない	JSDoc コメントの形式が正しくない、または不完全	@param {Type} と @returns {Type} があることを確認する
VS Code で型エラーが発生する	JSDoc の型構文が正しくない	{?string} ではなく、{string|null} のような TypeScript 形式の型を使用する
型インポートが壊れている	@typedef のインポートパスが間違っている	正しいパスで @typedef {import('./file').TypeName} を使用する
ジェネリック型が機能しない	@template の使い方が正しくない	パラメーターで使用する前に @template T を宣言する
ドキュメントが生成されない	JSDoc ツールが設定されていない	適切な設定で jsdoc -c jsdoc.json を実行する
オプションのパラメーターが必須として表示される	パラメーター名に [] がない	@param {string} [optional] または {string=} を使用する
型が認識されない	誤字がある、または typedef が宣言されていない	使用前に @typedef で型を定義する
戻り値の型が無視される	@returns タグがない	@returns {Type} で戻り値を必ずドキュメント化する

関連スキル

• TSDoc/JSDoc
• TypeScript