# 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.

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

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

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

```ts
/**
 * 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](01_overview.md)