tsdoc

TSDoc comment guidelines

For tag details, syntax, and usage examples, see tags/<tag-name>.md refer to.

Mandatory rules

Use only TSDoc format (/** ... */) (// や /* */ is not recognized as TSDoc)
Use only tags supported by TypeDoc (custom tags are prohibited)
Write descriptions in Japanese
@param Use hyphen-separated notation for descriptions: @param name - 説明
@param Do not write types in (they are automatically inferred from TypeScript type information)
The first line is the summary — write it concisely in one sentence
If a detailed description is needed, insert a blank line and use @remarks use
For a component's Props interface, use @param Instead of that, write TSDoc for each property
export default For components, write TSDoc immediately before the component definition
For named exports (types, constants, utilities), write TSDoc immediately before each export

Available tags

Block tags

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

Modifier tags

@internal

Inline tags

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

Exports that require TSDoc

Target	Required level	Reason
Shared components (`shared-ui-*`）	Required	Public APIs used from multiple packages
Shared type definitions (`export interface/type`）	Required	Type contracts that cross package boundaries
Shared constants (`export const`）	Required	Public data definitions
Utility functions	Required	Clarify the intent of the logic
Custom hooks	Required	Explanation of usage and return values
features / widgets components	Recommended	Used from pages
pages components	Optional	Only used from app
Private helper functions	Optional	Only within the file

Templates by entity

React components (using 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 components (using Radix UI)

"use client" Even when using Radix UI, write this only when useState/useEffect/event handlers are required.

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

Type definitions (interface / type)

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

Constants and data objects

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

Utility functions

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

Custom hooks

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

`@category` Unified name

Category name	Target
`UI`	UI components (Button, Tag, Select, etc.)
`Layout`	Layout components (Container, Fieldset, etc.)
`Icon`	Icon-related components
`Model`	Type definitions, interfaces
`Data`	Constants, data objects
`Hooks`	Custom hooks
`Utils`	Utility functions
`Config`	Configuration-related

Common mistakes

@param write the type in → Not needed because it is automatically inferred from TypeScript.@param {string} name instead of @param name - 説明
For each property of Props, @param use → For interface properties, directly /** ... */ write
Write the component's TSDoc above the interface → Write it immediately before the component definition (const Component = ...)
@return use → In TSDoc, @returns(with a trailing s) is correct
@defaultValue use backticks in → Write the value as is (@defaultValue 2）
@example write code without a code fence in → Always enclose in ```tsx ... ``` enclose with
Writing verbose TSDoc for private helpers → A one-line summary is sufficient for functions used only within the file
@link do not add curly braces to → Inline tags require curly braces in {@link Target} requires curly braces with
The summary is too long → Keep the first line to one concise sentence. Separate details into @remarks separate into
@category inconsistency in → Use the unified names above

Directory structure

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

Search procedure

Derive the category from the task, and identify the target page in the category's README.md:

Find the category corresponding to the task in the mapping table below
For tag details, directly Read tags/<tag-name>.md to check
For usage examples, refer to samples/README.md and then Read the relevant page
For commands and configuration, refer to scripts/README.md and then Read the relevant page

Task → Category mapping

Task	Category	Reference
`@param` / `@returns` / `@throws` want to check the syntax of	tags	tags/param.md, tags/returns.md, tags/throws.md
`@remarks` / `@example` / `@see` want to know how to use	tags	tags/remarks.md, tags/example.md, tags/see.md
`@deprecated` / `@internal` / `@since` want to know how to use	tags	tags/deprecated.md, tags/internal.md, tags/since.md
`@defaultValue` / `@category` / `@typeParam` / `{@link}` want to look up	tags	tags/default-value.md, tags/category.md, tags/type-param.md, tags/link.md
Want to know how to write typical TSDoc comments	samples	samples/README.md
Want to know the commands for installation, lint, and tsdoc.json configuration	scripts	scripts/README.md