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 する

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