jsdoc-tsdoc

JSDoc と TSDoc のドキュメント

完全なリファレンス：JavaScript の JSDoc 型注釈、TypeDoc/API Extractor の設定、ESLint プラグインのセットアップ、README テンプレートについては、advanced.md を参照してください。

詳細な情報：包括的なタグのリファレンスについては、technology に jsdoc を指定して mcp__documentation__fetch_docs を使用してください。

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

• プレーンな JavaScript プロジェクト - JavaScript 固有の JSDoc パターンには jsdoc スキルを使用してください
• コードコメント（API 以外） - TSDoc は公開 API のドキュメント用であり、コード内のコメント用ではありません
• コードから自動生成するドキュメント - TypeDoc または API Extractor ツールを直接使用してください

TSDoc と JSDoc の比較

機能	JSDoc	TSDoc
目的	JS のドキュメントと型	TS のドキュメントのみ
型注釈	@type、@param {Type}	不要（TS の型を使用）
標準化	デファクト	公式標準

TypeScript プロジェクトでは TSDoc を使用してください - 型は TypeScript から取得され、コメントでは動作を説明します。

関数のドキュメント

/**
 * Calculates the total price including tax.
 *
 * @remarks
 * This method uses the default tax rate unless overridden.
 * For international orders, use {@link calculateInternationalPrice} instead.
 *
 * @param basePrice - The pre-tax price in cents
 * @param taxRate - Tax rate as decimal (default: 0.1 for 10%)
 * @returns The total price including tax in cents
 *
 * @throws {@link InvalidPriceError}
 * Thrown if basePrice is negative
 *
 * @example
 * ```typescript
 * const total = calculateTotalPrice(1000, 0.08);
 * console.log(total); // 1080
 * ```
 *
 * @beta
 */
function calculateTotalPrice(basePrice: number, taxRate = 0.1): number {
  if (basePrice < 0) {
    throw new InvalidPriceError('Price cannot be negative');
  }
  return Math.round(basePrice * (1 + taxRate));
}

インターフェースのドキュメント

/**
 * Configuration options for the HTTP client.
 *
 * @remarks
 * All timeouts are in milliseconds.
 *
 * @public
 */
interface HttpClientOptions {
  /**
   * Base URL for all requests.
   * @example 'https://api.example.com/v1'
   */
  baseUrl: string;

  /**
   * Request timeout in milliseconds.
   * @defaultValue 30000
   */
  timeout?: number;

  /**
   * Maximum number of retry attempts for failed requests.
   * @defaultValue 3
   */
  maxRetries?: number;
}

TSDoc タグ一覧

ブロックタグ

タグ	用途
@param name - description	パラメーターの説明
@returns description	戻り値の説明
@throws {Type} description	スローされる例外
@example	使用例（コードブロック）
@remarks	詳細な説明
@see	関連する参照
@deprecated reason	非推奨としてマーク
@defaultValue value	デフォルト値
@typeParam T - description	ジェネリック型パラメーター

修飾タグ

タグ	意味
@public	公開 API の一部
@internal	内部実装
@alpha	初期プレビュー。変更される可能性があります
@beta	成熟段階。API が変更される可能性があります
@readonly	読み取り専用プロパティ
@override	親をオーバーライド

インラインタグ

タグ	用途
{@link Target}	シンボルへのリンク
{@link Target | text}	カスタムテキスト付きのリンク
{@inheritDoc Parent.method}	ドキュメントを継承

アンチパターン

アンチパターン	問題点	正しいアプローチ
TypeScript で型をドキュメント化する	型はシグネチャにすでにあるため冗長です	型ではなく動作を説明する
関数シグネチャをコピーして貼り付ける	価値がなく、内容の不整合を招きます	目的、エッジケース、例を説明する
複雑な API に @example がない	ユーザーが使い方を理解できません	常に使用例を含める
移行方法を示さずに @deprecated を使用する	代わりに何を使えばよいかユーザーに伝わりません	@deprecated Use {@link newFunction} instead
@throws の説明がない	ユーザーが何を捕捉すればよいかわかりません	スローされるすべての例外を説明する

トラブルシューティングのクイックガイド

問題	診断	解決策
VS Code でホバー時にドキュメントが表示されない	JSDoc コメントの形式が不正です	/** で始まり、タグの構文が正しいことを確認してください
eslint-plugin-tsdoc のエラー	TSDoc の構文が無効です	TSDoc 仕様に従ってタグの書式を修正してください
TypeDoc がコメントを無視する	コメントの位置が誤っています	JSDoc を宣言の直前に配置してください
{@link} が解決されない	シンボル参照が正しくありません	完全修飾名またはインポートパスを使用してください

公式リファレンス

リソース	URL
TSDoc	https://tsdoc.org/
JSDoc	https://jsdoc.app/
TypeDoc	https://typedoc.org/
API Extractor	https://api-extractor.com/