docs: add api generation for components #1767
Conversation
batchu5
requested review from
Adi-204,
Florence-Njeri,
asyncapi-bot-eve,
derberg and
magicmatatjahu
as code owners
|
What reviewer looks at during PR reviewThe following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.
|
📝 WalkthroughWalkthroughAdds JSDoc-to-Markdown API generation tooling and generated API.md, new Handlebars template and helper, tightens and normalizes many JSDoc typedefs and examples across components, converts several default exports to named exports, adds a few runtime guards (CoreMethods, OnOpen), and updates package scripts and devDependencies. Most edits are documentation and typings. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (1)
packages/components/src/components/Models.js (1)
22-26: Reconsider the @Class documentation placement.This
@classJSDoc block documentsModelinaGenerator, but this class is not defined in this file—it's an external type imported from@asyncapi/modelina(e.g.,PythonGenerator,JavaGenerator, etc. on lines 3-9).Documenting external classes in your own codebase can be misleading to maintainers and documentation generators. Consider either:
- Removing this block entirely and relying on the library's own documentation
- Using
@typedefto create a type alias that references the external generator classesIf you want to keep type documentation, use a typedef instead:
-/** - * @class ModelinaGenerator - * @classdesc Represents a Modelina generator class. - * @param {object} [options] - Optional generator options. - */ +/** + * @typedef {import('@asyncapi/modelina').PythonGenerator | import('@asyncapi/modelina').JavaGenerator | import('@asyncapi/modelina').TypeScriptGenerator | import('@asyncapi/modelina').CSharpGenerator | import('@asyncapi/modelina').RustGenerator | import('@asyncapi/modelina').JavaScriptGenerator} ModelinaGenerator + * Represents any Modelina generator class instance. + */
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
packages/components/API.md(1 hunks)packages/components/api.hbs(1 hunks)packages/components/package.json(2 hunks)packages/components/src/components/CloseConnection.js(1 hunks)packages/components/src/components/HandleMessage.js(1 hunks)packages/components/src/components/MethodGenerator.js(2 hunks)packages/components/src/components/Models.js(1 hunks)packages/components/src/components/QueryParamsVariables.js(1 hunks)packages/components/src/components/RegisterErrorHandler.js(1 hunks)packages/components/src/components/RegisterMessageHandler.js(1 hunks)packages/components/src/components/SendOperations.js(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-05-12T14:23:48.919Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with action property (send/receive) and references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe operations
3. Messages are defined under a 'messages' container in channels
4. The specification decouples operations, channels and messages to improve reusability
5. Servers can use a 'host' property
Applied to files:
packages/components/src/components/SendOperations.jspackages/components/API.md
📚 Learning: 2025-05-12T14:23:48.919Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1551
File: apps/generator/docs/generator-template.md:45-73
Timestamp: 2025-05-12T14:23:48.919Z
Learning: AsyncAPI 3.0.0 specification introduces significant structural changes from 2.x:
1. Operations become top-level elements with references to channels
2. Channels use 'address' for the topic path instead of having nested publish/subscribe
3. Messages are defined under a 'messages' container in channels
4. Servers can use a 'host' property
Applied to files:
packages/components/API.md
📚 Learning: 2025-05-12T14:57:35.024Z
Learnt from: Adi-204
Repo: asyncapi/generator PR: 1557
File: packages/templates/clients/websocket/javascript/components/SendOperation.js:21-21
Timestamp: 2025-05-12T14:57:35.024Z
Learning: In the AsyncAPI generator templates, particularly in the JavaScript WebSocket client, single quotes are used for string literals inside template-generated code (which is itself inside backticks) to preserve template placeholders like ${variable} as literal text in the generated code output.
Applied to files:
packages/components/API.md
🪛 LanguageTool
packages/components/API.md
[grammar] ~2-~2: Use a hyphen to join words.
Context: ...ection method with optional pre and post execution logic.
Parameters
| Name...
(QB_NEW_EN_HYPHEN)
[grammar] ~54-~54: Use a hyphen to join words.
Context: ...andler method with optional pre and post execution logic.
Parameters
| Name...
(QB_NEW_EN_HYPHEN)
[grammar] ~150-~150: Use a hyphen to join words.
Context: ...ration method with optional pre and post execution logic.
Parameters
| Name...
(QB_NEW_EN_HYPHEN)
[grammar] ~163-~163: Use a hyphen to join words.
Context: ...ration method with optional pre and post execution logic.
Parameters
| Name...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
packages/components/API.md
4-4: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
17-17: Multiple headings with the same content
(MD024, no-duplicate-heading)
18-18: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
25-25: Multiple headings with the same content
(MD024, no-duplicate-heading)
26-26: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
34-34: Multiple headings with the same content
(MD024, no-duplicate-heading)
35-35: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
45-45: Multiple headings with the same content
(MD024, no-duplicate-heading)
46-46: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
55-55: Multiple headings with the same content
(MD024, no-duplicate-heading)
56-56: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
72-72: Multiple headings with the same content
(MD024, no-duplicate-heading)
73-73: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
86-86: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
90-90: Multiple headings with the same content
(MD024, no-duplicate-heading)
91-91: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
102-102: Multiple headings with the same content
(MD024, no-duplicate-heading)
103-103: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
111-111: Multiple headings with the same content
(MD024, no-duplicate-heading)
112-112: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
118-118: Multiple headings with the same content
(MD024, no-duplicate-heading)
119-119: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
125-125: Multiple headings with the same content
(MD024, no-duplicate-heading)
126-126: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
134-134: Multiple headings with the same content
(MD024, no-duplicate-heading)
135-135: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
142-142: Multiple headings with the same content
(MD024, no-duplicate-heading)
143-143: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
151-151: Multiple headings with the same content
(MD024, no-duplicate-heading)
152-152: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
164-164: Multiple headings with the same content
(MD024, no-duplicate-heading)
165-165: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
177-177: Multiple headings with the same content
(MD024, no-duplicate-heading)
178-178: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (4)
packages/components/src/components/Models.js (1)
30-30: LGTM: Improved type reference.Changing from an inline constructor signature to the named
ModelinaGeneratortype improves readability and maintainability.packages/components/src/components/SendOperations.js (1)
9-24: LGTM: Well-structured type definitions.The new
SendOperationMethodsandSendOperationGeneratortype definitions improve code documentation and type clarity. The refactoring from an inline type to named types makes the API more maintainable.packages/components/package.json (2)
13-13: No issues found — jsdoc2md command and paths are correctly configured.The verification confirms:
- Template file
api.hbsexists atpackages/components/api.hbs✓- Glob pattern
./src/**/*.jscorrectly matches all 16 source files ✓- Relative path resolution works as expected from the npm script execution context ✓
43-43: No issues found—version 9.1.3 is current and compatible.jsdoc-to-markdown v9.1.3 requires Node.js >= 12.17.0, and the version was released on October 3, 2025, making it current. The specified version is appropriate for the project.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
packages/components/API.md (1)
1-193: Update JSDoc comments in four component files to correct hyphenation.The auto-generated API.md reflects the current state of JSDoc comments in source files. Verification confirms that grammar issues identified in the previous review have not yet been fixed. Update "pre and post execution" to "pre- and post-execution" in the following files:
packages/components/src/components/CloseConnection.jspackages/components/src/components/HandleMessage.jspackages/components/src/components/RegisterErrorHandler.jspackages/components/src/components/RegisterMessageHandler.jsOnce source JSDoc is corrected, the auto-generated API.md will reflect these changes.
🧹 Nitpick comments (1)
packages/components/package.json (1)
15-19: Consider adding API.md to the published package files.The
filesarray currently excludes the auto-generatedAPI.md. Since this is user-facing API documentation, consider whether it should be included in npm package distributions for end-users to reference.If
API.mdshould be published, add it to thefilesarray:"files": [ "lib/**", "README.md", + "API.md", "LICENSE" ],Alternatively, if
API.mdis only for the repository, ensure it's in.gitignoreand document this decision.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
packages/components/API.md(1 hunks)packages/components/api.hbs(1 hunks)packages/components/package.json(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/components/api.hbs
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-04-23T09:18:38.333Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1512
File: packages/templates/clients/websocket/javascript/components/AvailableOperations.js:10-15
Timestamp: 2025-04-23T09:18:38.333Z
Learning: In the asyncapi/generator repository, keys aren't required when mapping over operations array in the AvailableOperations component, contrary to the typical React pattern.
Applied to files:
packages/components/package.json
📚 Learning: 2025-05-12T14:57:35.024Z
Learnt from: Adi-204
Repo: asyncapi/generator PR: 1557
File: packages/templates/clients/websocket/javascript/components/SendOperation.js:21-21
Timestamp: 2025-05-12T14:57:35.024Z
Learning: In the AsyncAPI generator templates, particularly in the JavaScript WebSocket client, single quotes are used for string literals inside template-generated code (which is itself inside backticks) to preserve template placeholders like ${variable} as literal text in the generated code output.
Applied to files:
packages/components/API.md
🪛 LanguageTool
packages/components/API.md
[grammar] ~2-~2: Use a hyphen to join words.
Context: ...ection method with optional pre and post execution logic. ### Parameters | Name |...
(QB_NEW_EN_HYPHEN)
[grammar] ~58-~58: Use a hyphen to join words.
Context: ...andler method with optional pre and post execution logic. ### Parameters | Name |...
(QB_NEW_EN_HYPHEN)
[grammar] ~157-~157: Use a hyphen to join words.
Context: ...ration method with optional pre and post execution logic. ### Parameters | Name |...
(QB_NEW_EN_HYPHEN)
[grammar] ~171-~171: Use a hyphen to join words.
Context: ...ration method with optional pre and post execution logic. ### Parameters | Name |...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
packages/components/API.md
4-4: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
18-18: Multiple headings with the same content
(MD024, no-duplicate-heading)
19-19: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
26-26: Multiple headings with the same content
(MD024, no-duplicate-heading)
27-27: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
33-33: Multiple headings with the same content
(MD024, no-duplicate-heading)
36-36: Multiple headings with the same content
(MD024, no-duplicate-heading)
37-37: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
45-45: Multiple headings with the same content
(MD024, no-duplicate-heading)
48-48: Multiple headings with the same content
(MD024, no-duplicate-heading)
49-49: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
56-56: Multiple headings with the same content
(MD024, no-duplicate-heading)
59-59: Multiple headings with the same content
(MD024, no-duplicate-heading)
60-60: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
70-70: Multiple headings with the same content
(MD024, no-duplicate-heading)
77-77: Multiple headings with the same content
(MD024, no-duplicate-heading)
78-78: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
91-91: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
95-95: Multiple headings with the same content
(MD024, no-duplicate-heading)
96-96: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Multiple headings with the same content
(MD024, no-duplicate-heading)
108-108: Multiple headings with the same content
(MD024, no-duplicate-heading)
109-109: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
117-117: Multiple headings with the same content
(MD024, no-duplicate-heading)
118-118: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
124-124: Multiple headings with the same content
(MD024, no-duplicate-heading)
125-125: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
131-131: Multiple headings with the same content
(MD024, no-duplicate-heading)
132-132: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
140-140: Multiple headings with the same content
(MD024, no-duplicate-heading)
141-141: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
146-146: Multiple headings with the same content
(MD024, no-duplicate-heading)
149-149: Multiple headings with the same content
(MD024, no-duplicate-heading)
150-150: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
158-158: Multiple headings with the same content
(MD024, no-duplicate-heading)
159-159: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
169-169: Multiple headings with the same content
(MD024, no-duplicate-heading)
172-172: Multiple headings with the same content
(MD024, no-duplicate-heading)
173-173: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
182-182: Multiple headings with the same content
(MD024, no-duplicate-heading)
186-186: Multiple headings with the same content
(MD024, no-duplicate-heading)
187-187: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (1)
packages/components/package.json (1)
43-43: Dependency version is appropriate.The jsdoc-to-markdown v9.1.3 version with caret constraint
^9.1.3is suitable for this use case, allowing patch and minor updates while maintaining stability.
… acroos platforms
batchu5
force-pushed
the
api-generation-for-components
branch
from
ef164c0 to
c521c81
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/components/package.json (1)
15-19: Consider addingAPI.mdto the published files array.The
API.mdfile is generated by thedocsscript and added to the published package alongsideREADME.mdandLICENSE. Confirm whether it should be included in thefilesarray for distribution to package consumers.If
API.mdis meant to be published, apply this diff:"files": [ "lib/**", "README.md", + "API.md", "LICENSE" ],
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/components/package.json(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-04-23T09:18:38.333Z
Learnt from: derberg
Repo: asyncapi/generator PR: 1512
File: packages/templates/clients/websocket/javascript/components/AvailableOperations.js:10-15
Timestamp: 2025-04-23T09:18:38.333Z
Learning: In the asyncapi/generator repository, keys aren't required when mapping over operations array in the AvailableOperations component, contrary to the typical React pattern.
Applied to files:
packages/components/package.json
🔇 Additional comments (1)
packages/components/package.json (1)
12-13: Cross-platform script fixes and glob quoting are correctly applied.The scripts properly use
&&for sequential execution (addressing the prior Unix-only&issue) and the glob pattern is correctly quoted for cross-platform compatibility. The workflow ensuresdocsruns afterprepublishOnlyto generate API documentation.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @packages/components/package.json:
- Line 13: The "docs" npm script uses the jsdoc2md CLI but the package
jsdoc-to-markdown is not declared in devDependencies; add "jsdoc-to-markdown" to
the package.json devDependencies (or run npm/yarn add --dev jsdoc-to-markdown)
so the jsdoc2md command is available for "docs" and "generate:assets"; update
the devDependencies block to include the exact package name and a compatible
version and run install to ensure the CLI is present.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
packages/components/package.jsonpackages/components/src/components/SendOperations.js
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/components/src/components/SendOperations.js
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Update relevant Generator documentation to accurately reflect PR changes introduced
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Applies to **/*.{js,ts,jsx,tsx} : Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions
📚 Learning: 2026-01-05T09:57:34.800Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Update relevant Generator documentation to accurately reflect PR changes introduced
Applied to files:
packages/components/package.json
📚 Learning: 2026-01-05T09:57:34.800Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: .github/pr-review-checklist.md:0-0
Timestamp: 2026-01-05T09:57:34.800Z
Learning: Applies to **/*.{js,ts,jsx,tsx} : Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions
Applied to files:
packages/components/package.json
🔇 Additional comments (2)
packages/components/package.json (2)
15-20: LGTM!Including
API.mdin the published files ensures consumers have access to the generated API documentation.
12-12: LGTM!The workflow correctly builds first (
prepublishOnly) before running docs generation, ensuring thelib/directory exists whenjsdoc2mdprocesses./lib/**/*.js.
batchu5
force-pushed
the
api-generation-for-components
branch
from
0142c2e to
97c4e57
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/components/src/components/readme/CoreMethods.js (1)
14-30: Guard against unsupported languages to avoid a runtime crash.
methodConfig[language]can beundefined, which will throw on destructuring. Add a guard (or explicit fallback) and document the error condition in JSDoc.✅ Suggested fix (guard + JSDoc error condition)
/** * Renders a list of core WebSocket client methods for a given target language. - * `@param` {Object} props - Component props - * `@param` {string} props.language - Target language used to select method names. + * `@param` {{ language: string }} props - Component props. + * `@param` {string} props.language - Target language used to select method names. * `@returns` {JSX.Element} A Text Component that contains a list of core client methods. + * `@throws` {Error} When the provided language is not supported. * * `@example` * const language = "javascript"; * return ( * <CoreMethods language={language} /> * ) */ export function CoreMethods({ language }) { const config = methodConfig[language]; + if (!config) { + throw new Error(`Unsupported language: ${language}`); + } const { msgHandler, errHandler } = config;
♻️ Duplicate comments (1)
packages/components/src/components/readme/AvailableOperations.js (1)
2-3: Import statements still use default import syntax.This issue was previously flagged. The imports for
OperationHeaderandMessageExamplesneed to be updated to use named import syntax since these components were converted to named exports.
🧹 Nitpick comments (1)
packages/components/src/components/readme/Overview.js (1)
3-37: Standardize JSDoc types/casing and make the example self‑contained.Minor consistency issues in types and wording, plus the example omits the Overview import. Consider the tweaks below. As per coding guidelines, ...
♻️ Suggested JSDoc cleanup
/** * Renders an overview section for a WebSocket client. * Displays the API description, version, and server URL. * - * `@param` {Object} props - Component props - * `@param` {object} props.info - Info object from the AsyncAPI document. + * `@param` {Object} props - Component props. + * `@param` {Object} props.info - Info object from the AsyncAPI document. * `@param` {string} props.title - Title from the AsyncAPI document. - * `@param` {string} props.serverUrl - ServerUrl from a specific server from the AsyncAPI document. - * `@returns` {JSX.Element} A Text Component that contains the Overview of a Websocket client. + * `@param` {string} props.serverUrl - Server URL from a specific server in the AsyncAPI document. + * `@returns` {JSX.Element} A Text component that contains the overview of a WebSocket client. * * `@example` * * import path from "path"; * import { Parser, fromFile } from "@asyncapi/parser"; * import { getServer, getServerUrl } from '@asyncapi/generator-helpers'; + * import { Overview } from './Overview'; * * async function renderOverview(){
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/components/docs/API.md`:
- Around line 331-352: The example defines an async function renderFileHeader
but never invokes it; update the snippet to call renderFileHeader() and handle
errors (e.g., await renderFileHeader() inside an async IIFE or call .catch on
the returned promise) so the snippet is runnable and surfaces parsing failures
from fromFile/Parser; apply the same invocation + minimal error handling pattern
to other async examples that return promises (reference symbols:
renderFileHeader, Parser, fromFile, FileHeaderInfo).
🧹 Nitpick comments (1)
packages/components/src/components/readme/MessageExamples.js (1)
39-44: Tidy the return description wording.
There’s a small grammar hiccup (“…examples. or null…”). Consider making it a single sentence for readability.💡 Suggested edit
-* `@returns` {React.ReactNode} A Text Component that contains message examples. or null when no examples exist. +* `@returns` {React.ReactNode} A Text Component that contains message examples, or null when no examples exist.
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/components/src/components/readme/Usage.js (1)
37-63: Add explicit error condition and document it.
usageConfig[language]can be undefined, leading to a confusing runtime TypeError. Consider guarding and documenting the error case in JSDoc. As per coding guidelines, include error conditions.🛠️ Proposed update
/** * Renders a usage example snippet for a generated client in a given language. * `@param` {Object} props - Component props * `@param` {string} props.clientName - The Exported name of the client. * `@param` {string} props.clientFileName - The file name where the client is defined. * `@param` {Language} props.language - The target language for which to render the usage snippet + * `@throws` {Error} When an unsupported language is provided. * `@returns` {JSX.Element} A Text component containing a formatted usage example snippet. * * `@example` @@ export function Usage({ clientName, clientFileName, language }) { const snippetFn = usageConfig[language]; + if (!snippetFn) { + throw new Error(`Unsupported language: ${language}`); + } const snippet = snippetFn(clientName, clientFileName);
♻️ Duplicate comments (1)
packages/components/docs/API.md (1)
331-352: Async examples aren’t invoked (non‑runnable snippets).The async examples define functions but never call them. This makes the snippets incomplete for copy‑paste. Please invoke the functions (and add minimal error handling) in the source JSDoc, then regenerate API.md. This applies to other async examples too (Models, QueryParamsVariables, AvailableOperations, MessageExamples, OperationHeader, Overview, Readme, SendOperations). Based on learnings, keep the explicit async function pattern and invoke it.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/components/src/components/QueryParamsVariables.js`:
- Around line 112-116: The code calls generateParamCode(param) without ensuring
resolveQueryParamLogic returned a function when props.framework is omitted;
update QueryParamsVariables to guard against undefined by checking
resolveQueryParamLogic(props.language, props.framework) before using it (or
provide a default no-op generator), and handle both call sites (the block around
generateParamCode and the similar logic at 150-158) so that when framework is
absent you either supply a safe fallback generator or skip generation and return
null; reference resolveQueryParamLogic, generateParamCode, and the
QueryParamsVariables component when applying the change.
♻️ Duplicate comments (1)
packages/components/src/components/QueryParamsVariables.js (1)
10-14: Makeindent/newLinesoptional in the typedef.
Runtime objects omit these fields in several cases, so the current JSDoc implies required properties that aren’t always present.♻️ Suggested tweak
- * `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} variableDefinition - Code block for variable initialization. - * `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} ifCondition - Conditional statement block. - * `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} assignment - Code block assigning query param. - * `@property` {{ text: string, indent: number | undefined, newLines: number | undefined } | null} [closing] - Optional closing block (for braces, etc.). + * `@property` {{ text: string, indent?: number, newLines?: number }} variableDefinition - Code block for variable initialization. + * `@property` {{ text: string, indent?: number, newLines?: number }} ifCondition - Conditional statement block. + * `@property` {{ text: string, indent?: number, newLines?: number }} assignment - Code block assigning query param. + * `@property` {{ text: string, indent?: number, newLines?: number } | null} [closing] - Optional closing block (for braces, etc.).As per coding guidelines, keep JSDoc precise and consistent.
| * @param {Language} props.language - The target programming language. | ||
| * @param {string} [props.framework=''] - Optional framework for the language. | ||
| * @param {string[][]} props.queryParams - Array of query parameters, each represented as [paramName, paramType?]. | ||
| * @returns {React.ReactNode[]|null} Array of Text components for each query parameter, or null if queryParams is invalid. | ||
| * |
There was a problem hiding this comment.
Guard generateParamCode when framework is omitted.
For language="java" and no matching framework, resolveQueryParamLogic returns undefined, and generateParamCode(param) will throw. Either enforce a framework in the JSDoc or add a safe fallback.
✅ Safer fallback
- const generateParamCode = resolveQueryParamLogic(language, framework);
+ const generateParamCode = resolveQueryParamLogic(language, framework);
+ if (!generateParamCode) {
+ return null;
+ }As per coding guidelines, keep JSDoc accurate with runtime behavior.
Also applies to: 150-158
🤖 Prompt for AI Agents
In `@packages/components/src/components/QueryParamsVariables.js` around lines 112
- 116, The code calls generateParamCode(param) without ensuring
resolveQueryParamLogic returned a function when props.framework is omitted;
update QueryParamsVariables to guard against undefined by checking
resolveQueryParamLogic(props.language, props.framework) before using it (or
provide a default no-op generator), and handle both call sites (the block around
generateParamCode and the similar logic at 150-158) so that when framework is
absent you either supply a safe fallback generator or skip generation and return
null; reference resolveQueryParamLogic, generateParamCode, and the
QueryParamsVariables component when applying the change.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/components/src/components/MethodGenerator.js (1)
8-17: JSDoc type is missingparameterWrapproperty.The typedef on line 10 doesn't include
parameterWrap, but the runtime config (lines 13-16) defines it for all languages. This creates an inconsistency with thecustomMethodConfigJSDoc on line 74, which correctly includesparameterWrap.Suggested fix
-* `@type` {Record<Language, { returnType: string | undefined, openingTag: string | undefined, closingTag: string | undefined, indentSize: number | undefined }>} +* `@type` {Record<Language, { returnType: string | undefined, openingTag: string | undefined, closingTag: string | undefined, indentSize: number | undefined, parameterWrap: boolean | undefined }>}Based on coding guidelines, JSDoc comments should be clear and consistent, including accurate type information.
🤖 Fix all issues with AI agents
In `@packages/components/src/components/RegisterMessageHandler.js`:
- Around line 8-11: The config type in RegisterMessageHandler.js currently
requires a methodDocs property (as methodDocs: string | undefined) but the
python config omits it, so change the type for the record entry to make
methodDocs optional (e.g., use methodDocs?: string or methodDocs?: string |
undefined) so entries can omit it; update the Record<Language, { methodDocs: ...
, methodLogic: string }> declaration accordingly to reflect optionality in the
RegisterMessageHandler configuration.
♻️ Duplicate comments (3)
packages/components/src/components/Models.js (1)
22-25: Typedef describes instances, not constructors.The typedef is named
ModelinaGeneratorConstructorbut the types (PythonGenerator | JavaGenerator | ...) represent instances. SincegeneratorConfigstores constructor references (not instances), consider usingtypeofsyntax:{typeof PythonGenerator | typeof JavaGenerator | ...}.packages/components/src/components/QueryParamsVariables.js (1)
10-14: Make QueryParamCodeBlock properties optional (matches runtime).
These blocks often omitnewLines(and sometimesindent), sonumber | undefinedstill implies the property exists. Prefer optional props. This mirrors an earlier comment on the same issue.Suggested fix
-* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} variableDefinition - Code block for variable initialization. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} ifCondition - Conditional statement block. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} assignment - Code block assigning query param. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined } | null} [closing] - Optional closing block (for braces, etc.). +* `@property` {{ text: string, indent?: number, newLines?: number }} variableDefinition - Code block for variable initialization. +* `@property` {{ text: string, indent?: number, newLines?: number }} ifCondition - Conditional statement block. +* `@property` {{ text: string, indent?: number, newLines?: number }} assignment - Code block assigning query param. +* `@property` {{ text: string, indent?: number, newLines?: number } | null} [closing] - Optional closing block (for braces, etc.).As per coding guidelines, keep JSDoc accurate with runtime behavior.
packages/components/src/components/CloseConnection.js (1)
16-19: MakemethodDocsoptional to match the config shape.
Thepythonconfig omitsmethodDocsentirely, while other languages include it. The JSDoc should reflect this optional property.Suggested fix
-* `@type` {Record<Language, { methodDocs: string | undefined, methodLogic: string }>} +* `@type` {Record<Language, { methodDocs?: string, methodLogic: string }>}
🧹 Nitpick comments (3)
packages/components/src/components/MethodGenerator.js (1)
79-104: Minor: Example uses Python-style parameter naming for Java.The example declares
language = "java"but uses"self"inmethodParams(line 82), which is a Python convention. For Java consistency, consider using conventional parameter names.Suggested improvement
- * const methodParams = ["self", "handler"]; + * const methodParams = ["Handler handler"];packages/components/src/components/HandleMessage.js (1)
10-11: Type annotation mismatch with runtime structure.The type
{ methodDocs: string | undefined, methodLogic: string }impliesmethodDocsis always present (but may beundefined). However, thepythonentry (lines 13-18) omitsmethodDocsentirely. For accuracy,{ methodDocs?: string, methodLogic: string }would better reflect the actual structure where the property may be absent.Since this is JSDoc for documentation purposes and the current annotation communicates the intent (methodDocs may not have a value), this is a minor inconsistency.
♻️ Suggested fix for type accuracy
/** * Configuration for WebSocket message handler method logic per language. - * `@type` {Record<Language, { methodDocs: string | undefined, methodLogic: string }>} + * `@type` {Record<Language, { methodDocs?: string, methodLogic: string }>} */packages/components/src/components/readme/MessageExamples.js (1)
45-66: Consider addingMessageExamplesimport in the example snippet.
If the example is meant to be copy‑pasteable, include the component import so readers can run it without guessing.Suggested addition
* import path from "path"; * import { Parser, fromFile } from "@asyncapi/parser"; +* import { MessageExamples } from "@asyncapi/generator-components";As per coding guidelines, keep JSDoc examples clear and complete.
|
@Adi-204 |
|
@batchu5 the components you mentioned are used internally for readme hence not exported but if for readme generation we need please add them to index.js. |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/components/src/components/HandleMessage.js (1)
10-19: Type annotation doesn't match thepythonentry.The type
{ methodDocs: string | undefined, methodLogic: string }requiresmethodDocsto be present. However, thepythonconfiguration (lines 13–18) omits this property entirely. Either use an optional property annotation or add the property explicitly.Option A: Make the property optional
-* `@type` {Record<Language, { methodDocs: string | undefined, methodLogic: string }>} +* `@type` {Record<Language, { methodDocs?: string, methodLogic: string }>}Option B: Add explicit undefined to python entry
const websocketHandleMessageConfig = { python: { + methodDocs: undefined, methodLogic: `if len(self.message_handlers) == 0: print("\\033[94mReceived raw message:\\033[0m", message) else: for handler in self.message_handlers: handler(message)` },packages/components/src/components/CloseConnection.js (1)
18-26: Type annotation doesn't match runtime structure.The typedef declares
methodDocs: string | undefined, which requires the property to exist on every entry. However, thepythonconfig object (lines 21-26) omits themethodDocsproperty entirely. Use optional property syntax to match the runtime structure.Suggested fix
-* `@type` {Record<Language, { methodDocs: string | undefined, methodLogic: string }>} +* `@type` {Record<Language, { methodDocs?: string, methodLogic: string }>}
🤖 Fix all issues with AI agents
In `@packages/components/docs/API.md`:
- Around line 248-260: The example in the API.md uses a top-level "return (...)"
which is invalid JS; update the snippet so the JSX is wrapped in an executable
construct (e.g., a function like renderExample() that returns the <Connect ...
/> JSX, or assign the JSX to a const such as connectExample) so readers can run
it as-is; locate the example block showing Connect with props language and title
and replace the top-level return with one of these valid wrappers.
♻️ Duplicate comments (1)
packages/components/src/components/QueryParamsVariables.js (1)
11-14: Type annotation doesn't match runtime structure.The typedef declares properties like
indent: number | undefinedandnewLines: number | undefined, which requires these properties to exist. However, examining the runtime config (e.g., lines 27-40 for Python), many objects omitnewLinesentirely. Use optional property syntax to accurately reflect the structure.Suggested fix
* `@typedef` {Object} QueryParamCodeBlock -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} variableDefinition - Code block for variable initialization. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} ifCondition - Conditional statement block. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined }} assignment - Code block assigning query param. -* `@property` {{ text: string, indent: number | undefined, newLines: number | undefined } | null} [closing] - Optional closing block (for braces, etc.). +* `@property` {{ text: string, indent?: number, newLines?: number }} variableDefinition - Code block for variable initialization. +* `@property` {{ text: string, indent?: number, newLines?: number }} ifCondition - Conditional statement block. +* `@property` {{ text: string, indent?: number, newLines?: number }} assignment - Code block assigning query param. +* `@property` {{ text: string, indent?: number, newLines?: number } | null} [closing] - Optional closing block (for braces, etc.).
🧹 Nitpick comments (3)
packages/components/src/components/readme/Usage.js (2)
3-6: JSDoc typedef format should place description before the tag.The description "Supported programming languages." appears after the
@typedefdeclaration, which is non-standard. For proper rendering in documentation generators, the description should precede the tag or be inline.Suggested format
/** - * `@typedef` {'python' | 'javascript' } Language - * Supported programming languages. + * Supported programming languages. + * `@typedef` {'python' | 'javascript'} Language */
37-60: Good JSDoc coverage; minor text inconsistencies to fix.The documentation is comprehensive with proper
@param,@returns, and@exampletags. A couple of minor text issues:
- Line 41: "The Exported name" → "The exported name" (lowercase 'e')
- Line 42: Extra space after the dash ("clientFileName - The")
Suggested fixes
* `@param` {Object} props - Component props - * `@param` {string} props.clientName - The Exported name of the client. - * `@param` {string} props.clientFileName - The file name where the client is defined. + * `@param` {string} props.clientName - The exported name of the client. + * `@param` {string} props.clientFileName - The file name where the client is defined. * `@param` {Language} props.language - The target language for which to render the usage snippetBased on learnings and coding guidelines, JSDoc comments should be clear and consistent.
packages/components/src/index.js (1)
20-23: Inconsistent quote style.Lines 21-23 use double quotes while the rest of the file uses single quotes. Consider using consistent quote style throughout the file.
Suggested fix
export { Readme } from './components/readme/Readme'; -export { AvailableOperations } from "./components/readme/AvailableOperations"; -export { OperationHeader } from "./components/readme/OperationHeader"; -export { MessageExamples } from "./components/readme/MessageExamples"; +export { AvailableOperations } from './components/readme/AvailableOperations'; +export { OperationHeader } from './components/readme/OperationHeader'; +export { MessageExamples } from './components/readme/MessageExamples';
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/components/src/components/OnClose.js (1)
63-90: Guard against missing framework variants (java).
props.frameworkis documented as optional, but forlanguage="java"the resolver can returnundefined, causing a TypeError ongenerateOnCloseCode(title). Either document thatframeworkis required for languages with variants, or add a guard/fallback. As per coding guidelines, error conditions or constraints should be documented.🛠️ Suggested guard to avoid runtime crash
if (websocketOnCloseMethod[language]) { const generateOnCloseCode = resolveCloseConfig(language, framework); - const closeResult = generateOnCloseCode(title); - onCloseMethod = closeResult.onCloseMethod; - indent = closeResult.indent ?? 0; + if (typeof generateOnCloseCode === 'function') { + const closeResult = generateOnCloseCode(title); + onCloseMethod = closeResult.onCloseMethod; + indent = closeResult.indent ?? 0; + } }
🤖 Fix all issues with AI agents
In `@packages/components/src/components/Models.js`:
- Around line 54-59: The JSDoc in Models.js declares defaults for props.presets
and props.constraints as {} but the function signature doesn't set those
defaults; update the function signature for the Models component (the exported
Models function) to include default values for presets and constraints (e.g.,
presets = {} and constraints = {}) and adjust any truthy checks in the function
that rely on those defaults, or alternatively remove the {} defaults from the
JSDoc; after updating, regenerate packages/components/docs/API.md so the docs
match the code.
In `@packages/components/src/components/OnOpen.js`:
- Around line 53-72: The OnOpen component currently assumes an object-based
config exists when calling resolveOpenConfig(props.language, props.framework)
which can return undefined if framework is missing (causing
generateOnOpenCode(title) to throw); update OnOpen to validate the resolved
config and framework early: if language requires a framework (object-based
configs) and framework is absent or resolveOpenConfig returns undefined, throw a
clear Error with context (e.g., "Missing or invalid framework for language X")
before calling generateOnOpenCode, add a JSDoc `@throws` to the component and/or
resolveOpenConfig documenting this error, and update any callers/tests
accordingly to pass a valid framework or handle the thrown error.
♻️ Duplicate comments (2)
packages/components/docs/API.md (1)
203-223: Fix top-levelreturnstatements in synchronous examples.Multiple synchronous examples use top-level
returnstatements, which is invalid JavaScript outside of a function context. This prevents users from copy-pasting and running the examples. This pattern appears in:
- CloseConnection (lines 212-222)
- Connect (lines 254-259) - previously flagged but not yet addressed
- DependencyProvider (lines 295-302)
- OnClose (lines 558-564)
- OnError (lines 593-595)
- OnMessage (lines 624-626)
- CoreMethods (lines 799-801)
- Installation (lines 830-832)
- Usage (lines 1079-1085)
- RegisterErrorHandler (lines 1125-1134)
- RegisterMessageHandler (lines 1172-1180)
Wrap these in executable functions or assign the JSX to a const, similar to the pattern used in async examples. As per coding guidelines, ensure JSDoc examples are runnable and complete.
✏️ Suggested pattern (apply to all affected components)
Option 1 - Wrap in a render function:
-return ( - <Connect - language={language} - title={title} - /> -) +function renderConnect() { + return ( + <Connect + language={language} + title={title} + /> + ); +}Option 2 - Assign to a const:
-return ( - <Connect - language={language} - title={title} - /> -) +const connectElement = ( + <Connect + language={language} + title={title} + /> +);Update the source JSDoc in the affected component files, then regenerate API.md by running
npm run docsin the packages/components directory.Based on learnings, clear and consistent JSDoc comments with runnable examples are required.
Also applies to: 248-260, 289-303, 554-565, 592-596, 623-627, 798-802, 829-833, 1075-1086, 1118-1135, 1166-1181
packages/components/src/components/Models.js (1)
22-30: Use constructor types (typeof) for generator classes.The typedef still describes instances, but
generatorConfigstores class constructors. Update the typedef to usetypeofso tooling reflects the correct shape.🔧 Proposed JSDoc correction
-/** - * `@typedef` {PythonGenerator | JavaGenerator | TypeScriptGenerator | CSharpGenerator | RustGenerator | JavaScriptGenerator} ModelinaGeneratorConstructor - * Represents any Modelina generator constructor. - */ +/** + * `@typedef` {typeof PythonGenerator | typeof JavaGenerator | typeof TypeScriptGenerator | typeof CSharpGenerator | typeof RustGenerator | typeof JavaScriptGenerator} ModelinaGeneratorConstructor + * Represents any Modelina generator constructor. + */JSDoc type syntax for constructor types using typeof Class vs new(...) signatures
🧹 Nitpick comments (1)
packages/components/src/components/OnError.js (1)
9-12: Tighten the mapping type for clearer API docs.
The mapping always returns{ onErrorMethod: string }, so the JSDoc can be more precise.♻️ Proposed update
- * `@type` {Object.<Language, Function>} + * `@type` {Object.<Language, () => { onErrorMethod: string }>}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/components/src/components/OnOpen.js`:
- Around line 8-12: The JSDoc for websocketOnOpenMethod is incorrect: it
currently declares Object.<Language, Function> but the map includes entries like
the java key that are objects of framework-specific functions; update the JSDoc
to accurately reflect the union shape (e.g., a Function or a map of
framework->Function) or add a typedef for the framework map and reference it;
locate websocketOnOpenMethod (and the java entry) in OnOpen.js and change the
comment to a union/typedef type that documents both Function and
Object.<Framework, Function>.
🧹 Nitpick comments (3)
packages/components/src/components/readme/CoreMethods.js (2)
3-6: Minor typedef formatting inconsistency.There's an extra space before the closing brace in the union type.
✏️ Suggested fix
-/** - * `@typedef` {'python' | 'javascript' } Language - * Supported programming languages. - */ +/** + * Supported programming languages. + * `@typedef` {'python' | 'javascript'} Language + */This also moves the description before the
@typedeftag, which is the conventional JSDoc placement for typedef descriptions.
37-39: Consider adding defensive handling for unsupported languages.If
languageis not'python'or'javascript',methodConfig[language]returnsundefined, causing a runtime error on destructuring at line 39. While theLanguagetypedef documents valid inputs, adding a guard could improve robustness.🛡️ Optional defensive check
export function CoreMethods({ language }) { const config = methodConfig[language]; + if (!config) { + throw new Error(`Unsupported language: ${language}. Expected 'python' or 'javascript'.`); + } const { msgHandler, errHandler } = config;This is a defensive coding suggestion for future-proofing; the current implementation works correctly when used as documented.
packages/components/src/components/HandleMessage.js (1)
10-10: Type annotation doesn't match actual data structure.The
pythonentry (lines 13-18) omitsmethodDocsentirely, but the type declares it asmethodDocs: string | undefined(property must exist, value can be undefined). For a property that may be absent, use optional syntax.Suggested fix
-* `@type` {Record<Language, { methodDocs: string | undefined, methodLogic: string }>} +* `@type` {Record<Language, { methodDocs?: string, methodLogic: string }>}
batchu5
force-pushed
the
api-generation-for-components
branch
from
2be5fc0 to
c4583e3
Compare
|
@Adi-204, I have made the changes as per the last conversation. Could you please review once more? |
|
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/components/src/components/OnClose.js (1)
91-96: Guard against undefinedgenerateOnCloseCodeto prevent TypeError.When
language='java'butframeworkis invalid (e.g.,'spring'),websocketOnCloseMethod['java']exists (passes line 91 check), butresolveCloseConfigreturnsundefined. Line 93 then throwsTypeError: generateOnCloseCode is not a function.🐛 Proposed fix
if (websocketOnCloseMethod[language]) { const generateOnCloseCode = resolveCloseConfig(language, framework); - const closeResult = generateOnCloseCode(title); - onCloseMethod = closeResult.onCloseMethod; - indent = closeResult.indent ?? 0; + if (typeof generateOnCloseCode === 'function') { + const closeResult = generateOnCloseCode(title); + onCloseMethod = closeResult.onCloseMethod; + indent = closeResult.indent ?? 0; + } }packages/components/src/components/OnOpen.js (1)
85-94: Throw on unsupported language to match the@throwscontract.
Right now, an unknownlanguagesilently returns an emptyText, which contradicts the JSDoc and can hide misconfigurations. Consider failing fast when the language isn’t supported.🐛 Proposed fix
- if (websocketOnOpenMethod[language]) { - const generateOnOpenCode = resolveOpenConfig(language, framework); - if (typeof generateOnOpenCode !== 'function') { - throw new Error(`Unsupported onOpen handler for language="${language}" framework="${framework}"`); - } - const openResult = generateOnOpenCode(title); - onOpenMethod = openResult.onOpenMethod; - indent = openResult.indent ?? 0; - newLines = openResult.newLines ?? 1; - } + if (!websocketOnOpenMethod[language]) { + throw new Error(`Unsupported onOpen handler for language="${language}" framework="${framework}"`); + } + const generateOnOpenCode = resolveOpenConfig(language, framework); + if (typeof generateOnOpenCode !== 'function') { + throw new Error(`Unsupported onOpen handler for language="${language}" framework="${framework}"`); + } + const openResult = generateOnOpenCode(title); + onOpenMethod = openResult.onOpenMethod; + indent = openResult.indent ?? 0; + newLines = openResult.newLines ?? 1;
🤖 Fix all issues with AI agents
In `@packages/components/src/components/MethodGenerator.js`:
- Around line 19-23: Add explicit `@param` and `@returns` JSDoc tags to the two
private helper functions in MethodGenerator.js (the one documented by the
"Resolve docs and logic for the given language + framework config." block and
the other helper around the 44-48 region). For each helper, document all
parameters by name with a brief type/description and add a `@returns` tag
describing the return value/type; keep the existing `@private` tag and ensure the
JSDoc names match the actual function parameter names so IDEs and linters pick
them up.
In `@packages/components/src/components/readme/CoreMethods.js`:
- Around line 19-35: The JSDoc for the CoreMethods component does not document
that it can throw for unsupported languages; update the comment block for
CoreMethods to include a `@throws` tag describing the error condition (e.g., when
props.language is not recognized) and the type/shape of the thrown error,
referencing the component name CoreMethods and the props.language parameter so
callers know this function may throw for unsupported language values.
🧹 Nitpick comments (1)
packages/components/src/components/OnClose.js (1)
50-58: Add JSDoc forresolveCloseConfighelper function.This function lacks documentation. Per coding guidelines, functions should have clear JSDoc comments including parameter types, return values, and error conditions.
📝 Suggested JSDoc
+/** + * Resolves the appropriate onClose code generator for the given language and optional framework. + * + * `@param` {Language} language - The target programming language. + * `@param` {string} [framework=''] - Optional framework variant (e.g., 'quarkus' for java). + * `@returns` {Function|undefined} The code generator function, or undefined if not found. + */ const resolveCloseConfig = (language, framework = '') => {Based on learnings, JSDoc comments should cover parameter types, return values, and error conditions.
| /** | ||
| * Resolve docs and logic for the given language + framework config. | ||
| * | ||
| * @private | ||
| */ |
There was a problem hiding this comment.
Add @param/@returns to private helpers for JSDoc consistency.
Both private helpers have JSDoc but no parameter/return annotations. As per coding guidelines, include these for clarity and consistency.
🔧 Suggested JSDoc additions
/**
* Resolve docs and logic for the given language + framework config.
*
* `@private`
+ * `@param` {Object} params
+ * `@param` {Language} params.language
+ * `@param` {string} [params.methodDocs]
+ * `@param` {string} [params.methodLogic]
+ * `@param` {Record<Language, { methodDocs: string | undefined, methodLogic: string | undefined } | Record<string, { methodDocs: string | undefined, methodLogic: string | undefined }>>} [params.methodConfig]
+ * `@param` {string} [params.framework]
+ * `@returns` {{ docs: string, logic: string }}
*/
const resolveDocsAndLogic = ({ language, methodDocs, methodLogic, methodConfig, framework }) => { /**
* Build indented method body.
*
* `@private`
+ * `@param` {string} logic
+ * `@param` {string} [preExecutionCode]
+ * `@param` {string} [postExecutionCode]
+ * `@param` {number} indentSize
+ * `@returns` {string}
*/
const buildIndentedLogic = (logic, preExecutionCode, postExecutionCode, indentSize) => {Also applies to: 44-48
🤖 Prompt for AI Agents
In `@packages/components/src/components/MethodGenerator.js` around lines 19 - 23,
Add explicit `@param` and `@returns` JSDoc tags to the two private helper functions
in MethodGenerator.js (the one documented by the "Resolve docs and logic for the
given language + framework config." block and the other helper around the 44-48
region). For each helper, document all parameters by name with a brief
type/description and add a `@returns` tag describing the return value/type; keep
the existing `@private` tag and ensure the JSDoc names match the actual function
parameter names so IDEs and linters pick them up.
| /** | ||
| * Renders a list of core WebSocket client methods for a given target language. | ||
| * @param {Object} props - Component props | ||
| * @param {Language} props.language - Target language used to select method names. | ||
| * @returns {JSX.Element} A Text component that contains a list of core client methods. | ||
| * | ||
| * @example | ||
| * const language = "javascript"; | ||
| * | ||
| * function renderCoreMethods() { | ||
| * return ( | ||
| * <CoreMethods language={language} /> | ||
| * ) | ||
| * } | ||
| * | ||
| * renderCoreMethods(); | ||
| */ |
There was a problem hiding this comment.
Document the thrown error in JSDoc.
The function can throw for unsupported languages, but the JSDoc does not mention it.
🔧 Suggested JSDoc update
/**
* Renders a list of core WebSocket client methods for a given target language.
* `@param` {Object} props - Component props
* `@param` {Language} props.language - Target language used to select method names.
* `@returns` {JSX.Element} A Text component that contains a list of core client methods.
+ * `@throws` {Error} When an unsupported language is provided.
*
* `@example`
* const language = "javascript";As per coding guidelines, please document error conditions in JSDoc.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Renders a list of core WebSocket client methods for a given target language. | |
| * @param {Object} props - Component props | |
| * @param {Language} props.language - Target language used to select method names. | |
| * @returns {JSX.Element} A Text component that contains a list of core client methods. | |
| * | |
| * @example | |
| * const language = "javascript"; | |
| * | |
| * function renderCoreMethods() { | |
| * return ( | |
| * <CoreMethods language={language} /> | |
| * ) | |
| * } | |
| * | |
| * renderCoreMethods(); | |
| */ | |
| /** | |
| * Renders a list of core WebSocket client methods for a given target language. | |
| * `@param` {Object} props - Component props | |
| * `@param` {Language} props.language - Target language used to select method names. | |
| * `@returns` {JSX.Element} A Text component that contains a list of core client methods. | |
| * `@throws` {Error} When an unsupported language is provided. | |
| * | |
| * `@example` | |
| * const language = "javascript"; | |
| * | |
| * function renderCoreMethods() { | |
| * return ( | |
| * <CoreMethods language={language} /> | |
| * ) | |
| * } | |
| * | |
| * renderCoreMethods(); | |
| */ |
🤖 Prompt for AI Agents
In `@packages/components/src/components/readme/CoreMethods.js` around lines 19 -
35, The JSDoc for the CoreMethods component does not document that it can throw
for unsupported languages; update the comment block for CoreMethods to include a
`@throws` tag describing the error condition (e.g., when props.language is not
recognized) and the type/shape of the thrown error, referencing the component
name CoreMethods and the props.language parameter so callers know this function
may throw for unsupported language values.
3 participants
Description
Adds automated API documentation generation for components using jsdoc-to-markdown and a custom Handlebars template.
This improves consistency and readability of the generated
API.mdfile.Changes
package.jsonscripts:generate:assetsnow runs bothprepublishOnlyanddocsdocsusesjsdoc2mdwith a customapi.hbstemplate to generateAPI.mdsrc/**/*.jsinto a clean Markdown API fileRelated issue(s)
Resolves #1656
Summary by CodeRabbit
New Features
Documentation
Refactor
Behavior
Chores
Tests
✏️ Tip: You can customize this high-level summary in your review settings.