tsdoc

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 类型信息自动推断）
• 第一行是概要（summary）——简洁地用一句话描述
• 如需详细说明，在空行后使用 @remarks
• 组件的 Props interface 应为每个属性编写 TSDoc，而不是使用 @param
• 对于 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）	必需	公开数据定义
工具函数	必需	明确逻辑意图
自定义 Hook	必需	说明用法和返回值
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）

即使使用 Radix UI，也只有在需要 useState/useEffect/事件处理程序时才编写 "use client"。

"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;

自定义 Hook

/**
 * デバウンスされた検索入力を管理するフック。
 *
 * @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	自定义 Hook
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 → 仅在文件内使用的函数，概要一行即可
8. 在 @link 中省略花括号 → 行内标签必须使用花括号，写作 {@link Target}
9. 概要过长 → 第一行应简洁地写成一句话。详细内容应分离到 @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/ 是一个标签对应一个页面的例外，没有 README.md；映射表会直接指向各个标签页面（这是没有 references/ 的指南型技能的例外模式）：

1. 在下方的映射表中查找与任务对应的类别
2. 直接 Read tags/<tag-name>.md，查看标签的详细信息（不存在 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