Tsdoc

TSDoc コメント ガイドライン

タグの詳細・構文・使用例は tags/<tag-name>.md を参照。

必須ルール

• TSDoc 形式（/** ... */）のみ使用する（// や /* */ は TSDoc として認識されない）
• TypeDoc がサポートするタグのみ使用する（独自タグは禁止）
• 説明文は日本語で記述する
• @param の説明にはハイフン区切りを使用する: @param name - 説明
• @param には型を記述しない（TypeScript の型情報から自動推論される）
• 1 行目は概要（summary）— 簡潔に 1 文で記述する
• 詳細説明が必要な場合は空行を挟んで @remarks を使用する
• コンポーネントの Props interface には @param ではなくプロパティごとに TSDoc を記述する
• export default のコンポーネントにはコンポーネント定義の直前に TSDoc を記述する
• named export（型、定数、ユーティリティ）には各 export の直前に TSDoc を記述する

使用可能なタグ

ブロックタグ

@param, @typeParam, @returns, @throws, @remarks, @example, @see, @deprecated, @defaultValue, @category, @since

モディファイアタグ

@internal

インラインタグ

{@link}, {@linkcode}, {@linkplain}

TSDoc が必要なエクスポート

エンティティ別テンプレート

React コンポーネント（tailwind-variants 使用）

import type { ComponentProps } from "react";
import { tv } from "tailwind-variants";
import type { VariantProps } from "tailwind-variants";

const styles = tv({
  base: "...",
  variants: {
    size: { sm: "...", md: "..." },
  },
  defaultVariants: { size: "md" },
});

interface Props extends ComponentProps<"div">, VariantProps<typeof styles> {
  /** 評価値（0〜5 の数値） */
  rating: number;
  /**
   * 小数点以下の桁数。
   *
   * @defaultValue 2
   */
  fractionDigits?: number;
}

/**
 * 星アイコンと数値で評価を表示するコンポーネント。
 *
 * @remarks
 * `size` バリアントで見た目を制御する。
 * `className` でルート要素のスタイルをオーバーライド可能。
 *
 * @example
 * ```tsx
 * <StarRating rating={4.5} />
 * <StarRating rating={3.0} size="sm" fractionDigits={1} />
 * ```
 *
 * @category UI
 */
const StarRating = ({ rating, size, fractionDigits = 2, className, ...rest }: Props) => {
  // ...
};

export default StarRating;

React コンポーネント（Radix UI 使用）

"use client" は Radix UI 使用時でも useState/useEffect/イベントハンドラが必要な場合のみ記述する。

"use client"; // useState/useEffect/イベントハンドラ使用時のみ

import * as SelectPrimitive from "@radix-ui/react-select";
import type { ComponentProps } from "react";

/** セレクトボックスの選択肢。 */
interface Option {
  /** 表示テキスト */
  label: string;
  /** フォーム送信時の値 */
  value: string;
}

interface Props extends ComponentProps<typeof SelectPrimitive.Root> {
  /** 選択肢のリスト */
  options: readonly Option[];
  /** 未選択時のプレースホルダーテキスト */
  placeholder?: string;
}

/**
 * Radix UI Select をベースにしたセレクトボックス。
 *
 * @remarks
 * アクセシビリティ対応済み。キーボード操作とスクリーンリーダーをサポートする。
 *
 * @example
 * ```tsx
 * <Select
 *   options={[
 *     { label: "東京都", value: "tokyo" },
 *     { label: "大阪府", value: "osaka" },
 *   ]}
 *   placeholder="選択してください"
 *   onValueChange={(value) => console.log(value)}
 * />
 * ```
 *
 * @category UI
 */
const Select = ({ options, placeholder, className, ...rest }: Props) => {
  // ...
};

export default Select;

型定義（interface / type）

/**
 * カテゴリカードに表示するアイテムの型。
 *
 * @category Model
 */
export interface CategoryCardItem {
  /** カテゴリの一意識別子 */
  id: string;
  /** カテゴリの表示名 */
  name: string;
  /** カテゴリのサムネイル画像 */
  image: StaticImageData;
  /** カテゴリ詳細ページへのパス */
  href: string;
}

定数・データオブジェクト

/**
 * 業種カテゴリの一覧データ。
 *
 * @remarks
 * トップページのカテゴリセクションで使用する。
 *
 * @category Data
 */
export const INDUSTRY_LIST = [
  // ...
] as const satisfies CategoryCardItem[];

ユーティリティ関数

/**
 * 画像ソースから `srcset` 属性用の文字列を解決する。
 *
 * @param srcSet - `StaticImageData` または文字列の画像ソース
 * @returns `srcset` 属性に使用する URL 文字列
 *
 * @internal
 */
const resolveSrcSet = (srcSet: StaticImageData | string): string =>
  typeof srcSet === "string" ? srcSet : srcSet.src;

カスタムフック

/**
 * デバウンスされた検索入力を管理するフック。
 *
 * @param initialQuery - 初期検索文字列
 * @param delay - デバウンス遅延時間（ミリ秒）
 * @returns デバウンスされた検索状態と更新関数
 *
 * @example
 * ```tsx
 * const { query, debouncedQuery, setQuery } = useSearchInput("", 300);
 * ```
 *
 * @category Hooks
 */
export const useSearchInput = (initialQuery: string, delay: number) => {
  // ...
};

@category 統一名

よくある間違い

1. `@param` に型を記述する → TypeScript から自動推論されるため不要。@param {string} name ではなく @param name - 説明 2. Props の各プロパティに `@param` を使う → interface のプロパティには直接 /** ... */ を記述する 3. コンポーネントの TSDoc を interface の上に書く → コンポーネント定義（const Component = ...）の直前に記述する 4. `@return` を使う → TSDoc では @returns（末尾に s）が正しい 5. `@defaultValue` にバッククォートを使う → 値をそのまま記述する（@defaultValue 2） 6. `@example` にコードフェンスなしでコードを書く → 必ず `tsx ... ` で囲む 7. 非公開ヘルパーに冗長な TSDoc を書く → ファイル内のみの関数は概要 1 行で十分 8. `@link` に波括弧を付けない → インラインタグは {@link Target} で波括弧が必要 9. 概要が長すぎる → 1 行目は 1 文で簡潔に。詳細は @remarks に分離する 10. `@category` の不統一 → 上記の統一名を使用する

ディレクトリ構成

skills/tsdoc/
  SKILL.md
  tags/
    param.md
    returns.md
    remarks.md
    example.md
    throws.md
    deprecated.md
    see.md
    internal.md
    default-value.md
    category.md
    since.md
    type-param.md
    link.md
  samples/
    README.md
    function-comment.md
    react-component.md
    interface-type.md
    custom-hook.md
    deprecation.md
    modifier-tags.md
    multiple-examples.md
    tsdoc-config.md
  scripts/
    README.md
    install.md
    lint.md
    config.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. タグの詳細は tags/<tag-name>.md を直接 Read して確認する 3. 使用例は samples/README.md を参照してから該当ページを Read する 4. コマンド・設定は scripts/README.md を参照してから該当ページを Read する

タスク → カテゴリ マッピング

Custom Hook Comment

Document a React custom hook with @param, @returns, and @example tags.

/**
 * Manages a debounced search query string.
 *
 * @param initialQuery - Initial value of the search input
 * @param delay - Debounce delay in milliseconds
 * @returns Object containing the raw query, debounced query, and setter function
 *
 * @example
 * ```tsx
 * const { query, debouncedQuery, setQuery } = useSearchInput("", 300);
 *
 * return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
 * ```
 *
 * @category Hooks
 */
export const useSearchInput = (initialQuery: string, delay: number) => {
  // implementation
};

Notes

• Describe each parameter individually with @param name - description; omit the TypeScript type
• @returns should describe the shape of the returned value, not just say "the return value"
• Use @category Hooks so hook references are grouped separately from components in generated docs
• If the hook can throw, add @throws with the error type and condition

Deprecation Comment

Mark an API as deprecated with a migration note using @deprecated and @see.

/**
 * Formats a date string in locale-specific format.
 *
 * @param date - The date to format
 * @returns Locale-formatted date string
 *
 * @deprecated Use {@link formatDate} from `date-utils` instead.
 * This function will be removed in v3.0.
 *
 * @see {@link formatDate}
 */
export function legacyFormatDate(date: Date): string {
  return date.toLocaleDateString();
}

/**
 * Formats a date using Intl.DateTimeFormat.
 *
 * @param date - The date to format
 * @param locale - BCP 47 locale string (default: `"en-US"`)
 * @returns Locale-formatted date string
 */
export function formatDate(date: Date, locale = "en-US"): string {
  return new Intl.DateTimeFormat(locale).format(date);
}

Notes

• @deprecated accepts a free-text message; always include a migration path or replacement API
• Use the inline tag {@link Target} (with curly braces) to link to the replacement symbol
• @see lists related symbols or URLs for additional context
• Documentation tools (TypeDoc, VS Code) surface @deprecated as a strikethrough warning in IntelliSense

Function Comment

Document a utility function with @param, @returns, and @example tags.

/**
 * Adds two numbers together.
 *
 * @param x - The first operand
 * @param y - The second operand
 * @returns The sum of x and y
 *
 * @example
 * ```ts
 * console.log(add(1, 1));  // 2
 * console.log(add(1, -1)); // 0
 * ```
 */
export function add(x: number, y: number): number {
  return x + y;
}

Notes

• @param uses a hyphen separator: @param name - description
• Do not include type annotations in @param; TypeScript infers them automatically
• @returns (not @return) is the correct TSDoc spelling
• Wrap code inside @example with a fenced code block using the appropriate language identifier

Interface and Type Comment

Document an exported interface with per-property TSDoc.

/**
 * Item displayed in a category card.
 *
 * @category Model
 */
export interface CategoryCardItem {
  /** Unique identifier for the category */
  id: string;
  /** Display name shown to the user */
  name: string;
  /** URL path to the category detail page */
  href: string;
  /** Optional thumbnail image URL */
  thumbnailUrl?: string;
}

Notes

• Write a single /** ... */ block above each property, not @param
• The interface-level block uses @category Model (or another unified name) to group types in generated docs
• Optional properties (?) should describe the default behaviour or absence semantics in their comment
• Avoid repeating the property name in the description (e.g., prefer "Display name shown…" over "The name that is displayed…")

Modifier Tags

Control API visibility with modifier tags such as @internal, @public, and @beta.

/**
 * Resolves a srcset string from a static image or plain URL.
 *
 * @param src - StaticImageData object or URL string
 * @returns URL string suitable for the `srcset` attribute
 *
 * @internal
 */
export function resolveSrcSet(src: StaticImageData | string): string {
  return typeof src === "string" ? src : src.src;
}

/**
 * Experimental streaming API — subject to change without notice.
 *
 * @param endpoint - WebSocket endpoint URL
 *
 * @beta
 */
export function connectStream(endpoint: string): WebSocket {
  return new WebSocket(endpoint);
}

/**
 * Stable public entry point for all callers.
 *
 * @public
 */
export function stableApi(): void {}

Notes

• Modifier tags have no content; place them at the end of the comment block
• @internal signals that API Extractor should strip the symbol from the public .d.ts rollup
• @beta marks the API as experimental; @alpha denotes even earlier-stage APIs
• @public is the default visibility; add it only when you need to be explicit after overriding a base-class modifier

Multiple Examples

Provide several named @example sections to cover distinct use cases.

/**
 * Parses a JSON file from disk and returns the typed result.
 *
 * @param filePath - Absolute path to the JSON file
 * @returns Parsed object, or `null` if the file is empty
 * @throws {@link ParseError} if the file content is not valid JSON
 *
 * @example Basic usage
 * ```ts
 * const config = parseJsonFile("/project/config.json");
 * ```
 *
 * @example With type parameter
 * ```ts
 * interface Config { debug: boolean; port: number; }
 * const config = parseJsonFile<Config>("/project/config.json");
 * console.log(config?.port); // 3000
 * ```
 *
 * @example Handling a missing file
 * ```ts
 * try {
 *   parseJsonFile("/nonexistent.json");
 * } catch (e) {
 *   console.error(e.message);
 * }
 * ```
 */
export function parseJsonFile<T = unknown>(filePath: string): T | null {
  // implementation
  return null;
}

Notes

• Text on the same line as @example becomes the section title; without a title, tools number examples sequentially
• Each @example block is independent; start a fresh fenced code block for every example
• Prefer named examples when an API has meaningfully different invocation patterns
• Code fence language identifiers (ts, tsx, json) control syntax highlighting in generated docs

React Component Comment

Document a React component with per-property TSDoc on the Props interface.

import type { ComponentProps } from "react";

interface Props extends ComponentProps<"button"> {
  /** Visual style variant */
  variant?: "primary" | "secondary";
  /** Shows a loading spinner and disables the button */
  loading?: boolean;
}

/**
 * Accessible button with variant and loading state support.
 *
 * @remarks
 * Forwards all native `<button>` attributes via rest props.
 *
 * @example
 * ```tsx
 * <Button variant="primary" onClick={handleSubmit}>
 *   Submit
 * </Button>
 *
 * <Button loading>Processing…</Button>
 * ```
 *
 * @category UI
 */
const Button = ({ variant = "primary", loading, children, ...rest }: Props) => {
  return (
    <button disabled={loading} {...rest}>
      {children}
    </button>
  );
};

export default Button;

Notes

• Write the component-level TSDoc directly above the const Component = ... definition, not above the Props interface
• Document each Props property with its own /** ... */ inline comment; do not use @param for props
• Place @remarks after the summary line, separated by a blank line, for extended descriptions
• Use @category UI (or another unified category name) to group components in generated docs

samples

tsdoc.json Configuration

Define custom tags in tsdoc.json and load the configuration programmatically.

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myCustomTag",
      "syntaxKind": "modifier"
    },
    {
      "tagName": "@scenario",
      "syntaxKind": "block",
      "allowMultiple": true
    }
  ]
}

Load the configuration in a custom tool:

import * as path from "path";
import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";
import { TSDocConfigFile } from "@microsoft/tsdoc-config";

const sourceFile = "src/example.ts";
const configFile = TSDocConfigFile.loadForFolder(path.dirname(sourceFile));

if (configFile.hasErrors) {
  console.log(configFile.getErrorSummary());
}

const config = new TSDocConfiguration();
configFile.configureParser(config);
const parser = new TSDocParser(config);

Sharing tags across projects via extends:

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-shared-package/dist/tsdoc-base.json",
    "./local/tsdoc-local.json"
  ]
}

Notes

• Place tsdoc.json in the same directory as tsconfig.json
• Local paths in extends must begin with ./ to distinguish them from npm package references
• syntaxKind accepts "modifier", "block", or "inline"
• Set "allowMultiple": true for block tags that may appear more than once per comment

Config

tsdoc.json 設定ファイルの作成と管理。

基本的な tsdoc.json の作成

# tsconfig.json と同じディレクトリに tsdoc.json を作成する

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myTag",
      "syntaxKind": "modifier"
    }
  ]
}

tsdoc.json は tsconfig.json または package.json が存在するディレクトリに配置する。ローダーがディレクトリを上方向に探索して最寄りの設定ファイルを読み込む。

共有設定の継承

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-package/dist/tsdoc-base.json",
    "./path/to/local/tsdoc-local.json"
  ]
}

ローカルファイルを参照する場合は ./ から始めるパスを指定する。./ なしの文字列は npm パッケージ名として解釈される。

Install

TSDoc 関連パッケージのインストール。

ESLint プラグインのインストール

npm install --save-dev eslint-plugin-tsdoc

TypeScript プロジェクトへの TSDoc 構文検証ルールを追加する。typescript-eslint セットアップ済みの環境が前提。

tsdoc-config パッケージのインストール

npm install @microsoft/tsdoc-config

tsdoc.json 設定ファイルの読み込みに使用するパッケージ。カスタムタグ定義や設定の継承が必要な場合にインストールする。

tsdoc パーサーのインストール

npm install @microsoft/tsdoc

TSDoc コメントのプログラム的な解析に使用するリファレンス実装。ドキュメント生成ツール（API Extractor、TypeDoc 等）が内部で使用する。

Lint

TSDoc 構文の検証と lint 実行。

TypeScript ファイルの TSDoc 構文チェック

npm run lint

package.json の lint スクリプトが eslint -f unix "src/**/*.{ts,tsx}" のように設定されている場合に実行する。

ESLint 設定への TSDoc プラグイン追加（.eslintrc.js）

# .eslintrc.js に以下を追加して tsdoc/syntax ルールを有効化する

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json",
    tsconfigRootDir: __dirname,
    ecmaVersion: 2018,
    sourceType: "module",
  },
  plugins: ["eslint-plugin-tsdoc"],
  rules: {
    "tsdoc/syntax": "warn",
  },
};

eslint-plugin-tsdoc のインストール後、上記設定を追加することで TSDoc 構文エラーを検出できる。

scripts

@category

TypeDoc のドキュメントでシンボルをグループ化するブロックタグ。

構文

@category カテゴリ名

プロジェクトのカテゴリ名

使用例

/**
 * 星アイコンと数値で評価を表示するコンポーネント。
 *
 * @category UI
 */
const StarRating = ({ ... }: Props) => { ... };

/**
 * カテゴリカードに表示するアイテムの型。
 *
 * @category Model
 */
export interface CategoryCardItem { ... }

/**
 * 業種カテゴリの一覧データ。
 *
 * @category Data
 */
export const INDUSTRY_LIST = [ ... ];

/**
 * Fieldset のコンテキスト値を取得するフック。
 *
 * @category Hooks
 */
export const useFieldset = () => useContext(FieldsetContext);

注意

• TypeDoc 独自のタグ（TSDoc 標準にはない）
• プロジェクト内で上記の統一名を使用する
• 1 つのシンボルに複数の @category を指定可能

@defaultValue

プロパティやパラメータのデフォルト値を明示するブロックタグ。

構文

@defaultValue 値

使用例

Props interface のプロパティ

interface Props extends ComponentProps<"div">, VariantProps<typeof styles> {
  /** 評価値（0〜5 の数値） */
  rating: number;
  /**
   * 小数点以下の桁数。
   *
   * @defaultValue 2
   */
  fractionDigits?: number;
}

tailwind-variants の defaultVariants 対応

interface Props extends ComponentProps<"button">, VariantProps<typeof styles> {
  /**
   * ボタンの視覚スタイル。
   *
   * @defaultValue "primary"
   */
  variant?: "primary" | "secondary" | "outline";
  /**
   * ボタンのサイズ。
   *
   * @defaultValue "md"
   */
  size?: "sm" | "md" | "lg";
}

注意

• バッククォートで値を囲まない（@defaultValue 2 が正しく、` @defaultValue 2 ` は不正）
• tailwind-variants の defaultVariants で設定される値と一致させる
• TypeDoc はこの値をプロパティの説明に表示する

@deprecated

非推奨であることを示すブロックタグ。TypeDoc で警告として表示される。

構文

@deprecated 代替手段の説明

使用例

関数の非推奨

/**
 * 企業情報を取得する。
 *
 * @deprecated {@link fetchCompanyV2} を使用してください。v3.0 で削除予定。
 */
export const fetchCompany = async (id: string): Promise<Company> => {
  // ...
};

コンポーネントの非推奨

/**
 * 旧スタイルのボタンコンポーネント。
 *
 * @deprecated `@repo/shared-ui-partial/ui/button` の Button を使用してください。
 */
const LegacyButton = ({ ... }: Props) => {
  // ...
};

export default LegacyButton;

注意

• 代替手段を必ず説明に含める
• {@link} で代替シンボルへのリンクを付けるとより有用
• TypeDoc はこのタグを警告アイコン付きで表示する

@example

使用例をコードブロックで示すブロックタグ。

構文

@example
` ` `tsx
// コード例
` ` `

タイトル付き:

@example 基本的な使用
` ` `tsx
// コード例
` ` `

使用例

コンポーネント

/**
 * 星アイコンと数値で評価を表示するコンポーネント。
 *
 * @example
 * ```tsx
 * <StarRating rating={4.5} />
 * ```
 *
 * @example バリアント指定
 * ```tsx
 * <StarRating rating={3.0} size="sm" fractionDigits={1} />
 * ```
 */

複数の使用例

/**
 * クリック可能な多態コンポーネント。
 *
 * @example ボタンとして使用
 * ```tsx
 * <Clickable onClick={handleClick}>送信</Clickable>
 * ```
 *
 * @example リンクとして使用
 * ```tsx
 * <Clickable href="/search">検索ページへ</Clickable>
 * ```
 *
 * @example 外部リンクとして使用
 * ```tsx
 * <Clickable href="https://example.com" target="_blank">外部サイト</Clickable>
 * ```
 */

注意

• 必ずコードフェンス（ `tsx ... ` ）で囲む（TypeDoc がコードブロックとして認識するために必要）
• 言語指定は tsx（React コンポーネント）または typescript（非コンポーネント）
• @example タイトル でタイトルを指定可能
• 複数の @example を記述可能

@internal

パッケージ外に公開しない内部シンボルを示すモディファイアタグ。

構文

@internal

使用例

/**
 * 画像ソースから srcset 属性用の文字列を解決する。
 *
 * @param srcSet - StaticImageData または文字列の画像ソース
 * @returns srcset 属性に使用する URL 文字列
 *
 * @internal
 */
const resolveSrcSet = (srcSet: StaticImageData | string): string =>
  typeof srcSet === "string" ? srcSet : srcSet.src;

/**
 * Fieldset のコンテキスト。
 *
 * @internal
 */
const FieldsetContext = createContext<FieldsetContextValue | null>(null);

注意

• TypeDoc の --excludeInternal オプションでドキュメントから除外できる
• エクスポートされていない関数は TypeDoc の対象外のため @internal は不要
• パッケージの subpath exports に含まれないがエクスポートされるヘルパーに有用
• モディファイアタグのため、説明テキストは付かない

{@link}

他のシンボルや URL へのインラインリンクを作成するインラインタグ。

構文

{@link SymbolName}             シンボル名がリンクテキストになる
{@link SymbolName | 表示名}     カスタムリンクテキスト
{@linkcode SymbolName}         コードフォントでリンク表示
{@linkplain SymbolName}        プレーンテキストでリンク表示

使用例

関連型への参照

/**
 * セレクトボックスコンポーネント。
 *
 * @remarks
 * 選択肢は {@link Option} 型の配列で指定する。
 * スタイルは {@linkcode styles} を参照。
 */

@see との併用

/**
 * Fieldset のルートコンポーネント。
 *
 * @see {@link useFieldset} コンテキスト値を取得するフック
 * @see {@link FieldsetContext | Fieldset コンテキスト} 内部コンテキスト定義
 */

@deprecated との併用

/**
 * @deprecated {@link fetchCompanyV2} を使用してください。
 */

注意

• インラインタグのため {} で囲む必要がある（@link だけでは動作しない）
• {@linkcode} はコードフォント（<code>）で表示される — 関数名や変数名に適している
• {@linkplain} はプレーンテキストで表示される
• @see や @deprecated の説明文内で使用することが多い

@param

関数やメソッドのパラメータを説明するブロックタグ。

構文

@param name - 説明

注意: 型は記述しない。TypeScript の型アノテーションから自動推論される。

使用例

関数

/**
 * ブレークポイントに対応するメディアクエリ文字列を解決する。
 *
 * @param source - 画像ソースの定義
 * @param defaultBp - ソースにブレークポイントが未指定の場合のデフォルト値
 * @returns メディアクエリ文字列（例: `"(min-width: 48rem)"`）
 */
const resolveMedia = (source: PictureSource, defaultBp: Breakpoint): string => {
  // ...
};

カスタムフック

/**
 * ローカルストレージと同期する状態管理フック。
 *
 * @param key - ローカルストレージのキー
 * @param initialValue - 初期値（ストレージに値がない場合に使用）
 * @returns 現在の値と更新関数のタプル
 */
export const useLocalStorage = <T>(key: string, initialValue: T) => {
  // ...
};

注意

• React コンポーネントの Props には @param を使わない — interface のプロパティに直接 /** ... */ を記述する
• ハイフン（-）で名前と説明を区切る（TSDoc 標準）
• 省略可能なパラメータのデフォルト値は @defaultValue で別途記述する
• @param {string} name のように型を含めない

@remarks

概要（1 行目）では伝えきれない詳細な説明を記述するブロックタグ。

構文

/**
 * 概要（1 行目）。
 *
 * @remarks
 * 詳細な説明をここに記述する。
 * 複数行にわたって記述可能。
 */

使用例

コンポーネントの動作説明

/**
 * リンクまたはボタンとして振る舞う多態コンポーネント。
 *
 * @remarks
 * `href` が指定された場合は `next/link` によるリンクとしてレンダリングする。
 * `href` が未指定の場合は `<button>` としてレンダリングする。
 *
 * `target="_blank"` の場合、`rel="noopener noreferrer"` が自動付与される。
 */

バリアントの説明

/**
 * タグラベルコンポーネント。
 *
 * @remarks
 * `color`、`size`、`radius` バリアントで見た目を制御する。
 * `asChild` を指定すると子要素にスタイルを委譲する。
 */

注意

• 概要と @remarks の間には空行を入れる
• 実装の理由（why）や注意点を記述するのに適している
• TypeDoc では概要と @remarks を別セクションとして表示する

@returns

関数の戻り値を説明するブロックタグ。

構文

@returns 説明

注意: @return ではなく @returns（末尾に s）を使用する。

使用例

ユーティリティ関数

/**
 * 画像ソースから srcset 属性用の文字列を解決する。
 *
 * @param srcSet - StaticImageData または文字列の画像ソース
 * @returns srcset 属性に使用する URL 文字列
 */
const resolveSrcSet = (srcSet: StaticImageData | string): string =>
  typeof srcSet === "string" ? srcSet : srcSet.src;

カスタムフック（オブジェクト戻り値）

/**
 * デバウンスされた検索入力を管理するフック。
 *
 * @param initialQuery - 初期検索文字列
 * @param delay - デバウンス遅延時間（ミリ秒）
 * @returns `query`（現在値）、`debouncedQuery`（遅延値）、`setQuery`（更新関数）を含むオブジェクト
 */
export const useSearchInput = (initialQuery: string, delay: number) => {
  // ...
};

注意

• React コンポーネントでは通常不要（JSX.Element を返すことが自明）
• 戻り値が void の場合は省略可
• カスタムフックでは戻り値のプロパティを説明すると有用

@see

関連するシンボルや外部リソースへの参照を示すブロックタグ。

構文

@see {@link TargetSymbol} 説明
@see https://example.com 説明

使用例

関連コンポーネントへの参照

/**
 * Radix UI Select をベースにしたセレクトボックス。
 *
 * @see {@link Option} 選択肢の型定義
 * @see https://www.radix-ui.com/docs/primitives/components/select Radix UI Select ドキュメント
 */

関連フックへの参照

/**
 * Fieldset のルートコンポーネント。
 *
 * @see {@link useFieldset} コンテキスト値を取得するフック
 */

注意

• シンボル参照には {@link} インラインタグを併用する
• 外部 URL はそのまま記述可能
• 複数の @see を記述可能

@since

シンボルが追加されたバージョンを示すブロックタグ。

構文

@since バージョン

使用例

/**
 * レスポンシブ対応の画像表示コンポーネント。
 *
 * @since 0.1.0
 * @category Layout
 */
const Picture = ({ ... }: Props) => { ... };

/**
 * デバウンスされた検索入力を管理するフック。
 *
 * @since 0.2.0
 * @category Hooks
 */
export const useSearchInput = (initialQuery: string, delay: number) => {
  // ...
};

注意

• パッケージのバージョニングが確立された後に使用する
• 現在のプロジェクトは初期開発フェーズのため、使用は任意
• 後から一括で追加することも可能

@throws

関数が投げる可能性のある例外を説明するブロックタグ。

構文

@throws {ErrorType} 条件の説明

使用例

/**
 * ユーザー情報を取得する。
 *
 * @param id - ユーザー ID
 * @returns ユーザー情報
 * @throws {NotFoundError} ユーザーが存在しない場合
 * @throws {AuthenticationError} 認証トークンが無効な場合
 */
export const fetchUser = async (id: string): Promise<User> => {
  // ...
};

注意

• API 通信関数や入力バリデーション関数で使用する
• UI コンポーネントではほとんど使用しない
• 複数の例外を投げる場合は @throws を複数記述する

@typeParam

ジェネリック型パラメータを説明するブロックタグ。

構文

@typeParam T - 説明

使用例

ジェネリック関数

/**
 * ローカルストレージと同期する状態管理フック。
 *
 * @typeParam T - ストレージに保存する値の型
 * @param key - ローカルストレージのキー
 * @param initialValue - 初期値
 * @returns 現在の値と更新関数のタプル
 */
export const useLocalStorage = <T>(key: string, initialValue: T) => {
  // ...
};

ジェネリック型

/**
 * API レスポンスのラッパー型。
 *
 * @typeParam T - レスポンスデータの型
 *
 * @category Model
 */
export interface ApiResponse<T> {
  /** レスポンスデータ */
  data: T;
  /** HTTP ステータスコード */
  status: number;
}

注意

• @param と同じくハイフン（-）で名前と説明を区切る
• ジェネリック型パラメータが自明な場合（T が唯一のパラメータで用途が明確）は省略可