TSDoc コメント ガイドライン

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

必須ルール

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

使用可能なタグ

ブロックタグ

TSDoc 標準タグのうち TypeDoc 0.28.20 が既定でサポートするものを使用する。

@param, @typeParam, @returns, @throws, @remarks, @privateRemarks, @example, @see, @deprecated, @defaultValue

モディファイアタグ

• リリースステージ: @public, @beta, @alpha, @experimental, @internal（@public は TypeDoc では可視性を上書きするため通常は省略。tags/public.md 参照）
• 継承・不変: @sealed, @virtual, @override, @readonly
• その他: @eventProperty, @packageDocumentation

インラインタグ

{@link}, {@inheritDoc}, {@label}

TSDoc 標準外の TypeDoc 拡張

@category, @since, {@linkcode}, {@linkplain}

• eslint-plugin-tsdoc と併用する場合は tsdoc.json に "extends": ["typedoc/tsdoc.json"] が必要
• @decorator は TSDoc 標準（Extended）だが TypeDoc の既定タグ一覧に無いため使用しない

TSDoc が必要なエクスポート

対象	必須レベル	理由
共有コンポーネント（shared-ui-*）	必須	複数パッケージから使用される公開 API
共有型定義（export interface/type）	必須	パッケージ境界をまたぐ型契約
共有定数（export const）	必須	公開データ定義
ユーティリティ関数	必須	ロジックの意図を明確化
カスタムフック	必須	使用方法と戻り値の説明
features / widgets コンポーネント	推奨	pages から使用される
pages コンポーネント	任意	app からの使用のみ
非公開ヘルパー関数	任意	ファイル内のみ

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

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 統一名

カテゴリ名	対象
UI	UI コンポーネント（Button, Tag, Select 等）
Layout	レイアウトコンポーネント（Container, Fieldset 等）
Icon	アイコン関連コンポーネント
Model	型定義、interface
Data	定数、データオブジェクト
Hooks	カスタムフック
Utils	ユーティリティ関数
Config	設定関連

よくある間違い

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 の不統一 → 上記の統一名を使用する
11. {@link Foo text}（パイプ無し）を書く → TSDoc 非準拠で TypeDoc のみ受け付ける。表示テキストは {@link Foo | text} と書く
12. @inheritDoc Ref を波括弧なしで書く → TSDoc ではインラインタグ。{@inheritDoc Ref} と書く（TypeDoc は波括弧なしも受け付けるが JSDoc 互換の扱い）

ディレクトリ構成

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
    public.md
    beta.md
    alpha.md
    experimental.md
    sealed.md
    virtual.md
    override.md
    readonly.md
    event-property.md
    package-documentation.md
    private-remarks.md
    inherit-doc.md
    label.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 で目的のページを特定する。ただし tags/ は 1 タグ 1 ページ構成の例外で README.md を持たず、マッピング表が各タグページを直接指す（references/ を持たないガイドライン型スキルの例外パターン）:

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

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

タスク	カテゴリ	参照先（tags は README 無しのため個別ページ直接）
@param / @returns / @throws の構文を確認したい	tags	tags/param.md, tags/returns.md, tags/throws.md
@remarks / @example / @see の使い方を知りたい	tags	tags/remarks.md, tags/example.md, tags/see.md
@deprecated / @internal / @since の使い方を知りたい	tags	tags/deprecated.md, tags/internal.md, tags/since.md
@defaultValue / @category / @typeParam / {@link} を調べたい	tags	tags/default-value.md, tags/category.md, tags/type-param.md, tags/link.md
リリースステージ（@public / @beta / @alpha / @experimental / @internal）を指定したい	tags	tags/public.md, tags/beta.md, tags/alpha.md, tags/experimental.md, tags/internal.md
継承・不変（@override / @sealed / @virtual / @readonly）を示したい	tags	tags/override.md, tags/sealed.md, tags/virtual.md, tags/readonly.md
パッケージ・ドキュメント制御（@packageDocumentation / @privateRemarks / {@inheritDoc} / {@label} / @eventProperty）を調べたい	tags	tags/package-documentation.md, tags/private-remarks.md, tags/inherit-doc.md, tags/label.md, tags/event-property.md
典型的な TSDoc コメントの書き方を知りたい	samples	samples/README.md
インストール・lint・tsdoc.json 設定のコマンドを知りたい	scripts	scripts/README.md