Skip to content

Commit 711c01d

Browse files
tribixbitetribixbite
committed
docs: Remove outdated DISCREPANCIES.md and related migration files, consolidate API reference into a single index.mdx, and implement redirects in docs.json for legacy links. Introduce JSDoc to MDX migration plan in JSDOC_MIGRATION_PLAN.md to streamline documentation generation and enhance contextual AI features. Update ROADMAP.md with new tasks for build script modernization and AI integration.
—cursor.gemini2.5-pro-max
1 parent 309f873 commit 711c01d

File tree

10 files changed

+479
-2240
lines changed

10 files changed

+479
-2240
lines changed

‎DISCREPANCIES.md

Lines changed: 0 additions & 59 deletions
This file was deleted.

‎JSDOC_MIGRATION_PLAN.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# JSDoc to MDX Migration and API Reference Consolidation Plan
2+
3+
This document outlines the strategy for creating a single, comprehensive, and AI-friendly API reference page from the existing JSDoc and TSDoc annotations.
4+
5+
## 1. Goal: A Single, Consolidated API Reference
6+
7+
The current API reference is spread across multiple files (`introduction.mdx`, `model.mdx`, `view.mdx`, etc.). This is inefficient for both users and AI assistants.
8+
9+
**The primary goal is to create a single `api-reference.mdx` file that contains the complete Core API documentation.**
10+
11+
This new file will be structured to be easily navigable using in-page hash links (e.g., `/api-reference#model`, `/api-reference#view-events`), providing a seamless user experience without page reloads.
12+
13+
## 2. Source of Truth
14+
15+
The canonical source for all API documentation will be the TSDoc annotations within `multisynq-client/client/types.d.ts`. This file is the most up-to-date and comprehensive resource.
16+
17+
Additional JSDoc from `multisynq-client/client/teatime/index.js` will be used for documenting system-level events (`view-join`, `view-exit`, `synced`).
18+
19+
## 3. Proposed Structure for `api-reference.mdx`
20+
21+
The consolidated file will be organized logically with clear, high-level sections. Each section will be a top-level `<h2>` heading, allowing for easy deep-linking.
22+
23+
```markdown
24+
# Core API Reference
25+
26+
<Note>
27+
This page provides a comprehensive reference for the Multisynq Core JavaScript API.
28+
</Note>
29+
30+
## Multisynq.Model
31+
<!-- All Model-related documentation goes here -->
32+
...
33+
34+
### Properties
35+
<!-- Model properties like .id, .sessionId, .viewCount -->
36+
...
37+
38+
### Static Methods
39+
<!-- Methods like Model.create(), Model.register() -->
40+
...
41+
42+
### Instance Methods
43+
<!-- Methods like .init(), .destroy(), .publish(), .subscribe(), .future() -->
44+
...
45+
46+
## Multisynq.View
47+
<!-- All View-related documentation goes here -->
48+
...
49+
50+
### Properties
51+
<!-- View properties like .viewId -->
52+
...
53+
54+
### Instance Methods
55+
<!-- Methods like .detach(), .publish(), .subscribe(), .now() -->
56+
...
57+
58+
## Multisynq.Session
59+
<!-- All Session-related documentation goes here -->
60+
...
61+
62+
### Methods
63+
<!-- Session.join() -->
64+
...
65+
66+
### Session Parameters
67+
<!-- Detailed breakdown of the parameters object for Session.join() -->
68+
...
69+
70+
## Multisynq.App
71+
<!-- All App utility documentation goes here -->
72+
...
73+
74+
## Multisynq.Data
75+
<!-- All Data API documentation goes here -->
76+
...
77+
78+
## System Events
79+
<!-- Documentation for view-join, view-exit, synced -->
80+
...
81+
```
82+
83+
## 4. JSDoc-to-MDX Automation Script (`jsdoc-to-mdx.js`)
84+
85+
An automation script is required to parse the source files and generate the `api-reference.mdx` file.
86+
87+
### Script Logic:
88+
1. **Parser Selection**: The script will use a robust JSDoc/TSDoc parser library (e.g., `jsdoc-to-markdown`, `typedoc`, or a custom parser) that can handle TSDoc syntax and extract the necessary comment blocks and code signatures.
89+
2. **Source Parsing**:
90+
* The script will primarily parse `multisynq-client/client/types.d.ts`.
91+
* It will also parse `multisynq-client/client/teatime/index.js` specifically to extract the `@event` blocks.
92+
3. **Data Extraction**: For each documented symbol (class, method, property, event), the script must extract:
93+
* Name (e.g., `Model.create`)
94+
* Description
95+
* Parameters (name, type, description, optional/required)
96+
* Return value (type, description)
97+
* Code examples (`@example`)
98+
* `@public`, `@deprecated`, `@since` tags.
99+
4. **MDX Generation**:
100+
* The script will iterate through the parsed data and generate MDX content using a template engine or direct string manipulation.
101+
* **Headers**: Each class (`Model`, `View`) will be an `<h2>`. Each method group (Static, Instance) will be an `<h3>`. Each individual method/property will be an `<h4>`.
102+
* **Signatures**: Method signatures will be placed in a `<CodeGroup>` or a simple code block.
103+
* **Parameters**: Parameters will be formatted using `<Fields>` or a markdown table for clarity.
104+
* **Examples**: Code examples will be placed in `<CodeGroup>` blocks with appropriate syntax highlighting.
105+
* **Descriptions**: The main description will be rendered as standard markdown, preserving formatting like lists and links.
106+
* **AI-Friendliness**: The script will follow the guidelines in `STYLE.md`, ensuring semantic headings, short paragraphs, and liberal use of components like `<Note>` and `<Warning>`.
107+
108+
## 5. Implementation Plan
109+
110+
1. **Task Creation**: A new task will be added to `ROADMAP.md` to track the creation of the JSDoc-to-MDX script and the consolidation of the API reference.
111+
2. **Script Development**: Develop the `docs/scripts/jsdoc-to-mdx.js` script.
112+
3. **Manual Consolidation (Interim)**: Manually create the first version of the consolidated `api-reference.mdx` by copying and pasting from the existing separate files. This provides an immediate benefit while the script is in development.
113+
4. **Integration**: Once the script is complete, replace the manual file with the auto-generated one.
114+
5. **CI/CD**: Integrate the script into a GitHub Action that runs on changes to the `multisynq-client` repository, ensuring the documentation is always up-to-date.
115+
6. **Cleanup**: Delete the old, separate API reference files (`model.mdx`, `view.mdx`, etc.) once the consolidated file is in place.
116+
117+
This plan ensures a clear path to a much-improved, maintainable, and user-friendly API reference.

‎ROADMAP.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,4 +96,13 @@ This next phase focuses on automating documentation generation, expanding conten
9696
- **Action**:
9797
1. Review every page that is not a direct copy from a source repository.
9898
2. Validate all API signatures, import paths, and architectural descriptions against the canonical sources of truth.
99-
3. Ensure there are no remaining fabricated examples or APIs.
99+
3. Ensure there are no remaining fabricated examples or APIs.
100+
101+
#### **8. ✅ Consolidate API Reference & Automate from JSDoc**
102+
103+
- **Goal**: Replace the fragmented API reference with a single, comprehensive page that is automatically generated from TSDoc/JSDoc comments in the source code.
104+
- **Plan**: Follow the detailed strategy outlined in `JSDOC_MIGRATION_PLAN.md`.
105+
- **Key Steps**:
106+
1. **Manual Consolidation (Interim)**: Combine `api-reference/introduction.mdx`, `api-reference/model.mdx`, `api-reference/view.mdx`, and `api-reference/session.mdx` into a single `api-reference/index.mdx`.
107+
2. **Script Development**: Create the `docs/scripts/jsdoc-to-mdx.js` automation script.
108+
3. **CI/CD Integration**: Set up a GitHub Action to run the script and keep the documentation in sync with the source code.

0 commit comments

Comments
 (0)