Vishesh 'ironeagle' Bangotra
12a2493c6c
Some checks reported errors
continuous-integration/drone/push Build was killed
1 line
9.4 KiB
JSON
1 line
9.4 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udea1 doc-weaver \u2014 TypeScript Documentation Weaver","text":"<p><code>doc-weaver</code> is the TypeScript counterpart to <code>doc-forge</code>. It compiles JSDoc-annotated TypeScript into a TypeDoc site (the MkDocs parallel) and a doc-forge-shaped MCP JSON bundle, so React packages document themselves for humans and agents alike.</p> <p>Doc model: this wiki is written for humans \u2014 guides and conventions. The authoritative API contracts live in the code (JSDoc) and the machine-readable bundle under <code>docs/mcp/</code>.</p>"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":"<ul> <li>\ud83e\uddf5 JSDoc extraction via TypeDoc (the TypeScript compiler API)</li> <li>\ud83e\uddec doc-forge-compatible MCP bundle (<code>index.json</code>, <code>nav.json</code>, <code>modules/*.json</code>)</li> <li>\u269b\ufe0f React-aware kinds \u2014 <code>component</code> (PascalCase) and <code>hook</code> (<code>use*</code>)</li> <li>\ud83d\udcda RDFC (React Doc-forge Convention) \u2014 the JSDoc parallel to GSDFC</li> <li>\ud83d\udd0c MCP server over stdio exposing <code>docs://index</code>, <code>docs://nav</code>, and <code>docs://modules/{module}</code></li> </ul>"},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"<pre><code>npm install\nnpm run build\n</code></pre> <p>This produces the <code>doc-weaver</code> binary under <code>bin/</code> and <code>dist/</code>.</p>"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview What doc-weaver is and how it fits RDFC Guide How to write RDFC-conformant JSDoc"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"<ul> <li>Source Code: the <code>doc-weaver</code> repository</li> <li>MCP Bundle: generated by <code>doc-weaver build --mcp --module src/index.ts</code> into <code>docs/mcp/</code></li> <li>Library Registry: registered in the standards hub as <code>doc-weaver</code> (MCP <code>:8010</code>)</li> </ul> <p>\u00a9 Aetoskia Internal \u2014 <code>doc-weaver</code> 0.1.0</p>"},{"location":"01_overview/","title":"Library Overview","text":"<p><code>doc-weaver</code> turns RDFC-compliant TypeScript JSDoc into maintainable reference documentation. It never edits source comments; it reads them, renders them, and assembles documentation from all available material \u2014 exactly as <code>doc-forge</code> does for Python docstrings.</p> <p>Analysis is static: source is parsed by the TypeScript compiler API via TypeDoc and is never executed.</p>"},{"location":"01_overview/#which-build-should-you-use","title":"\ud83e\udded Which Build Should You Use?","text":"Flag Source Output <code>--docs</code> (<code>--mkdocs</code>, <code>--lib</code>) JSDoc comments <code>site/lib/**</code> TypeDoc HTML (the MkDocs parallel) <code>--mcp</code> JSDoc comments + model <code>docs/mcp/**</code> doc-forge-shaped JSON <code>--api</code> OpenAPI spec reserved <code>--wiki</code> Hand-written markdown <code>docs/wiki/**</code> (unchanged)"},{"location":"01_overview/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","text":"<pre><code>TypeScript + JSDoc\n |\n TypeDoc (loader) -> serialized reflection JSON\n |\n TypeDocJsonToMCP (renderer) -> MCP bundle (docs/mcp/)\n generateHumanDocs (renderer) -> TypeDoc HTML site (site/lib/)\n</code></pre> <p>The MCP renderer and the human renderer never depend on each other: both read the same serialized reflections, so the machine bundle and the human site can never disagree about a symbol.</p>"},{"location":"01_overview/#mcp-bundle-shape","title":"\ud83d\udd04 MCP bundle shape","text":"<p><code>docs/mcp/**</code> is a self-contained, machine-readable reference whose shape is byte-compatible with <code>doc-forge</code>:</p> <pre><code>docs/mcp/\n index.json { project, type: \"docforge-model\", modules_count, source }\n nav.json [ { module, resource: \"docs://modules/<module>\" } ]\n modules/<module>.json { module, content: { path, docstring, objects } }\n</code></pre> <p><code>doc-weaver serve --mcp --module doc-weaver</code> serves it over stdio. See the RDFC Guide for how to write the JSDoc that fills it.</p>"},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":"<ul> <li>02 \u2013 RDFC Guide</li> </ul>"},{"location":"02_rdfc/","title":"RDFC Guide","text":"<p>RDFC \u2014 the React Doc-forge Convention \u2014 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.</p>"},{"location":"02_rdfc/#overview","title":"\ud83e\udded Overview","text":"<ul> <li>Documentation is the single source of truth and lives in JSDoc comments.</li> <li><code>doc-weaver</code> compiles comments; it never rewrites or invents them.</li> <li>Structure follows the TypeScript export hierarchy.</li> <li>Every public export should have a complete and accurate JSDoc comment.</li> <li>Types live in signatures; do not duplicate them in prose unless a tag requires it.</li> </ul>"},{"location":"02_rdfc/#module-file-level","title":"\ud83d\udce6 Module (file) level","text":"<p>Document the file with a leading block comment. It becomes the module <code>docstring</code> in the MCP bundle.</p> <pre><code>/**\n * # Resource list\n *\n * Renders, filters, and paginates a resource collection.\n *\n * ---\n *\n * Notes:\n * - Reads configuration from the OpenAPI spec.\n * - Pagination is server-driven.\n */\n</code></pre>"},{"location":"02_rdfc/#components","title":"\ud83d\udce6 Components","text":"<p>Document the component function and its props. Components are classified automatically as <code>kind: \"component\"</code> (PascalCase name).</p> <pre><code>/**\n * Render a single resource row with actions.\n *\n * @param props - Component props.\n * @param props.item - The resource record to display.\n * @param props.onSelect - Invoked when the row is selected.\n * @returns The rendered row element.\n *\n * @example\n * ```tsx\n * <ResourceList item={record} onSelect={handleSelect} />\n * ```\n */\nexport function ResourceList(props: ListCellProps) {\n // ...\n}\n</code></pre>"},{"location":"02_rdfc/#hooks","title":"\ud83d\udce6 Hooks","text":"<p>Hooks are classified automatically as <code>kind: \"hook\"</code> (name starts with <code>use</code>).</p> <pre><code>/**\n * Subscribe to server-sent events for an item.\n *\n * @param url - SSE endpoint, or `null` to disable.\n * @param handlers - Event handlers keyed by event name.\n * @returns Connection state and the latest payload.\n *\n * @remarks\n * The subscription is torn down on unmount.\n */\nexport function useItemSse(url: string | null, handlers: ItemSseHandlers) {\n // ...\n}\n</code></pre>"},{"location":"02_rdfc/#types-interfaces-and-members","title":"\ud83d\udce6 Types, interfaces, and members","text":"<p>Document the type and each member. Members become nested <code>members</code> entries in the MCP bundle.</p> <pre><code>/**\n * A single display field extracted from an OpenAPI schema.\n */\nexport interface FieldConfig {\n /** Property name in the payload. */\n name: string;\n /** `x-edit-as: date` \u2014 edit a `date-time` field with a date input. */\n editAs?: string;\n /** Schema-level `default` used to seed create-form state. */\n defaultValue?: unknown;\n}\n</code></pre>"},{"location":"02_rdfc/#notes-subsection-grouping","title":"\ud83d\udce6 Notes subsection grouping","text":"<p>Group related information using labeled subsections (Markdown bold):</p> <pre><code>Notes:\n **Guarantees:**\n\n - deterministic output\n\n **Lifecycle:**\n\n - created during initialization\n - reused across renders\n</code></pre>"},{"location":"02_rdfc/#heading-map","title":"\ud83d\udce6 Heading map","text":"<p><code>doc-weaver</code> renders JSDoc block tags into stable markdown headings so both TypeDoc and the MCP bundle agree:</p> JSDoc tag Rendered heading <code>@param</code> <code>**Parameters:**</code> <code>@returns</code> / <code>@return</code> <code>**Returns:**</code> <code>@throws</code> <code>**Throws:**</code> <code>@example</code> <code>**Example:**</code> <code>@deprecated</code> <code>**Deprecated:**</code> <code>@see</code> <code>**See also:**</code> <code>@remarks</code> <code>**Remarks:**</code> other <code>**@tag:**</code>"},{"location":"02_rdfc/#mapping-to-output-kinds","title":"\ud83d\udce6 Mapping to output kinds","text":"TS construct <code>kind</code> interface / type alias <code>interface</code> / <code>type-alias</code> function component (PascalCase) <code>component</code> custom hook (<code>use*</code>) <code>hook</code> plain function <code>function</code> object / class member <code>property</code> / <code>method</code> const / let / var <code>variable</code> <p>An explicit <code>@kind</code> tag overrides the inferred kind.</p>"},{"location":"02_rdfc/#enforcement","title":"\ud83d\udee1\ufe0f Enforcement","text":"<p>Unlike doc-forge (which runs <code>pydoclint</code> in CI), <code>doc-weaver</code> performs no signature linting: TypeDoc extracts whatever JSDoc is present. Keep comments complete and accurate \u2014 they are the single source of truth for both the human site and the machine bundle.</p>"},{"location":"02_rdfc/#related","title":"Related","text":"<ul> <li>01 \u2013 Overview</li> </ul>"}]} |