Skip to content

RDFC Guide

RDFC — the React Doc-forge Convention — is the TypeScript counterpart to doc-forge's GSDFC. This page is the practical companion to the convention: how to write JSDoc so it renders correctly in the TypeDoc site and stays machine-parsable in the MCP bundle and by AI tooling.

🧭 Overview

  • Documentation is the single source of truth and lives in JSDoc comments.
  • doc-weaver compiles comments; it never rewrites or invents them.
  • Structure follows the TypeScript export hierarchy.
  • Every public export should have a complete and accurate JSDoc comment.
  • Types live in signatures; do not duplicate them in prose unless a tag requires it.

📦 Module (file) level

Document the file with a leading block comment. It becomes the module docstring in the MCP bundle.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/**
 * # Resource list
 *
 * Renders, filters, and paginates a resource collection.
 *
 * ---
 *
 * Notes:
 *     - Reads configuration from the OpenAPI spec.
 *     - Pagination is server-driven.
 */

📦 Components

Document the component function and its props. Components are classified automatically as kind: "component" (PascalCase name).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
/**
 * Render a single resource row with actions.
 *
 * @param props - Component props.
 * @param props.item - The resource record to display.
 * @param props.onSelect - Invoked when the row is selected.
 * @returns The rendered row element.
 *
 * @example
 * ```tsx
 * <ResourceList item={record} onSelect={handleSelect} />
 * ```
 */
export function ResourceList(props: ListCellProps) {
  // ...
}

📦 Hooks

Hooks are classified automatically as kind: "hook" (name starts with use).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
/**
 * Subscribe to server-sent events for an item.
 *
 * @param url - SSE endpoint, or `null` to disable.
 * @param handlers - Event handlers keyed by event name.
 * @returns Connection state and the latest payload.
 *
 * @remarks
 * The subscription is torn down on unmount.
 */
export function useItemSse(url: string | null, handlers: ItemSseHandlers) {
  // ...
}

📦 Types, interfaces, and members

Document the type and each member. Members become nested members entries in the MCP bundle.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/**
 * A single display field extracted from an OpenAPI schema.
 */
export interface FieldConfig {
  /** Property name in the payload. */
  name: string;
  /** `x-edit-as: date` — edit a `date-time` field with a date input. */
  editAs?: string;
  /** Schema-level `default` used to seed create-form state. */
  defaultValue?: unknown;
}

📦 Notes subsection grouping

Group related information using labeled subsections (Markdown bold):

1
2
3
4
5
6
7
8
9
Notes:
    **Guarantees:**

        - deterministic output

    **Lifecycle:**

        - created during initialization
        - reused across renders

📦 Heading map

doc-weaver renders JSDoc block tags into stable markdown headings so both TypeDoc and the MCP bundle agree:

JSDoc tag Rendered heading
@param **Parameters:**
@returns / @return **Returns:**
@throws **Throws:**
@example **Example:**
@deprecated **Deprecated:**
@see **See also:**
@remarks **Remarks:**
other **@tag:**

📦 Mapping to output kinds

TS construct kind
interface / type alias interface / type-alias
function component (PascalCase) component
custom hook (use*) hook
plain function function
object / class member property / method
const / let / var variable

An explicit @kind tag overrides the inferred kind.

🛡️ Enforcement

Unlike doc-forge (which runs pydoclint in CI), doc-weaver performs no signature linting: TypeDoc extracts whatever JSDoc is present. Keep comments complete and accurate — they are the single source of truth for both the human site and the machine bundle.