Vishesh 'ironeagle' Bangotra
aeb6e6b0f6
Some checks failed
continuous-integration/drone/tag Build is failing
TypeDoc + JSDoc (RDFC) compiler producing a TypeDoc site and a
doc-forge-shaped MCP bundle for React/TypeScript packages.
- TypeDoc loader + human-docs and MCP renderers, signature-level
parameter docs and default-export surfacing
- MCPServer over @modelcontextprotocol/sdk (docs://index, docs://nav,
docs://modules/{module}, ping tool)
- doc-weaver build / serve CLI
- RDFC convention guide and hand-written wiki
- packaged as @aetoskia/doc-weaver with an npm release pipeline
(build-and-publish-npm + backfill-npm-from-tags)
174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
# 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)
|