doc-weaver/docs/wiki/02_rdfc.md

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.

/**
 * # 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).

/**
 * 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).

/**
 * 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.

/**
 * 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):

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.

---

Related

• 01 – Overview