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 generated API documentation (API.md and an api.hbs template), updates package scripts/devDeps to produce API.md, and tightens multiple JSDoc typedefs across components (switching optional properties to explicit unions and adding typedef aliases). No runtime behavior changes. 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. 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.
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| {{#each params}} | ||
| | {{name}} | {{type.names.[0]}} | {{description}} | |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Use Handlebars-standard array index syntax.
The bracket notation .[0] is non-standard for Handlebars. Use .0 instead to access the first array element.
Apply this diff:
-| {{name}} | {{type.names.[0]}} | {{description}} |
+| {{name}} | {{type.names.0}} | {{description}} |📝 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.
| | {{name}} | {{type.names.[0]}} | {{description}} | | |
| | {{name}} | {{type.names.0}} | {{description}} | |
🤖 Prompt for AI Agents
In packages/components/api.hbs around line 9, the template uses non-standard
Handlebars bracket notation `.[0]` to access the first array element; replace
`{{type.names.[0]}}` with the Handlebars-standard `{{type.names.0}}` so the
template uses proper array index syntax and renders correctly.
packages/components/API.md
Outdated
| ## Functions | ||
| ### **CloseConnection** - Renders a WebSocket close connection method with optional pre and post execution logic. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | Programming language used for method formatting. | | ||
| | props.framework | string | Framework used, if any (e.g., 'quarkus' for Java). | | ||
| | props.methodName | string | Name of the method to generate. | | ||
| | props.methodParams | Array.<string> | List of parameters for the method. | | ||
| | props.preExecutionCode | string | Code to insert before the main function logic. | | ||
| | props.postExecutionCode | string | Code to insert after the main function logic. | | ||
| | props.indent | number | Indentation level for the method block. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **Connect** - Component that renders WebSocket connection method for the specified programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component properties. | | ||
| | props.language | SupportedLanguage | The programming language for which to generate connection code. | | ||
| | props.title | string | The title of the WebSocket server. | | ||
|
|
||
| ### **resolveDependencies** - Helper function to resolve dependencies based on language, framework, and role. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | language | Language | The programming language. | | ||
| | framework | string | The framework (e.g., 'quarkus' for Java). | | ||
| | role | string | The role (e.g., 'client', 'connector' for Java). | | ||
|
|
||
| @returns Array.<string> | ||
| ### **DependencyProvider** - Renders the top-of-file dependency statements for the selected programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | The programming language for which to render dependency statements. | | ||
| | props.framework | string | The framework (e.g., 'quarkus' for Java). | | ||
| | props.role | string | The role (e.g., 'client', 'connector' for Java). | | ||
| | props.additionalDependencies | Array.<string> | Optional additional dependencies to include. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **FileHeaderInfo** - Renders a file header with metadata information such as title, version, protocol, host, and path. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.info | object | Info object from the AsyncAPI document. | | ||
| | props.server | object | Server object from the AsyncAPI document. | | ||
| | props.language | Language | Programming language used for comment formatting. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **HandleMessage** - Renders a WebSocket message handler method with optional pre and post execution logic. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | Programming language used for method formatting. | | ||
| | props.methodName | string | Name of the method to generate. | | ||
| | props.methodParams | Array.<string> | List of parameters for the method. | | ||
| | props.preExecutionCode | string | Code to insert before the main function logic. | | ||
| | props.postExecutionCode | string | Code to insert after the main function logic. | | ||
| | props.customMethodConfig | Object | Optional overrides for default method configuration. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **resolveDocsAndLogic** - Resolve docs and logic for the given language + framework config. | ||
|
|
||
| ### **buildIndentedLogic** - Build indented method body. | ||
|
|
||
| ### **MethodGenerator** - Generic Method rendering component. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | Programming language used for method formatting. | | ||
| | props.methodName | string | Name of the method. | | ||
| | props.methodParams | Array.<string> | Method parameters. | | ||
| | props.methodDocs | string | Optional documentation string. | | ||
| | props.methodLogic | string | Core method logic. | | ||
| | props.preExecutionCode | string | Code before main logic. | | ||
| | props.postExecutionCode | string | Code after main logic. | | ||
| | props.indent | number | Indentation for the method block. | | ||
| | props.newLines | number | Number of new lines after method. | | ||
| | props.customMethodConfig | Object | Optional custom syntax configuration for the current language. | | ||
| | props.methodConfig | Record.<Language, ({methodDocs: string, methodLogic: string}|Record.<string, {methodDocs: string, methodLogic: string}>)> | Language-level or framework-level configuration. | | ||
| | props.framework | string | Framework name for nested configurations (e.g., 'quarkus' for Java). | | ||
|
|
||
| ### **Models** - Generates and returns an array of model files based on the AsyncAPI document. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | params | Object | The parameters for the function. | | ||
| | params.asyncapi | AsyncAPIDocumentInterface | Parsed AsyncAPI document object. | | ||
| | params.language | Language | Target programming language for the generated models. | | ||
| | params.format | Format | Naming format for generated files. | | ||
| | params.presets | object | Custom presets for the generator instance. | | ||
| | params.constraints | object | Custom constraints for the generator instance. | | ||
|
|
||
| @returns Array.<File> | ||
| ### **OnClose** - Component that renders WebSocket onClose event handler for the specified programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component properties. | | ||
| | props.language | SupportedLanguage | The programming language for which to generate onClose handler code. | | ||
| | props.framework | string | Optional framework variant (e.g., 'quarkus' for java). | | ||
| | props.title | string | The title of the WebSocket server. | | ||
|
|
||
| ### **OnError** - Component that renders WebSocket onError event handler for the specified programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component properties. | | ||
| | props.language | SupportedLanguage | The programming language for which to generate onError handler code. | | ||
|
|
||
| ### **OnMessage** - Component that renders WebSocket onMessage event handler for the specified programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component properties. | | ||
| | props.language | SupportedLanguage | The programming language for which to generate onMessage handler code. | | ||
|
|
||
| ### **OnOpen** - Component that renders WebSocket onOpen event handler for the specified programming language. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component properties. | | ||
| | props.language | SupportedLanguage | The programming language for which to generate onOpen handler code. | | ||
| | props.framework | string | Optional framework variant (e.g., 'quarkus' for java). | | ||
| | props.title | string | The title of the WebSocket server. | | ||
|
|
||
| ### **resolveQueryParamLogic** - Resolve the appropriate query parameter configuration function based on language and framework. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | language | SupportedLanguage | The target programming language. | | ||
| | framework | string | Optional framework (e.g., 'quarkus' for Java). | | ||
|
|
||
| @returns function | ||
| ### **QueryParamsVariables** - Component for rendering query parameter variables code. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | SupportedLanguage | The target programming language. | | ||
| | props.framework | string | Optional framework for the language. | | ||
| | props.queryParams | Array.<Array.<string>> | Array of query parameters, each represented as [paramName, paramType?]. | | ||
|
|
||
| ### **RegisterErrorHandler** - Renders a WebSocket error handler registration method with optional pre and post execution logic. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | Programming language used for method formatting. | | ||
| | props.methodName | string | Name of the method to generate. | | ||
| | props.methodParams | Array.<string> | List of parameters for the method. | | ||
| | props.preExecutionCode | string | Code to insert before the main function logic. | | ||
| | props.postExecutionCode | string | Code to insert after the main function logic. | | ||
| | props.customMethodConfig | Object | Optional overrides for default method configuration. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **RegisterMessageHandler** - Renders a WebSocket message handler registration method with optional pre and post execution logic. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | Language | Programming language used for method formatting. | | ||
| | props.methodName | string | Name of the method to generate. | | ||
| | props.methodParams | Array.<string> | List of parameters for the method. | | ||
| | props.preExecutionCode | string | Code to insert before the main function logic. | | ||
| | props.postExecutionCode | string | Code to insert after the main function logic. | | ||
|
|
||
| @returns JSX.Element | ||
| ### **SendOperations** - Component for rendering WebSocket send operation methods.Generates both static and instance methods for sending messages through WebSocket connections. | ||
| ### Parameters | ||
| | Name | Type | Description | | ||
| |------|------|-------------| | ||
| | props | Object | Component props. | | ||
| | props.language | SupportedLanguage | The target programming language. | | ||
| | props.sendOperations | Array.<Object> | Array of send operations from AsyncAPI document. | | ||
| | props.clientName | string | The name of the client class. | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Generated file - issues should be fixed in source.
This file is auto-generated by jsdoc2md from source JSDoc comments and the api.hbs template. Static analysis has flagged several issues:
- Line 86 table column count mismatch - The table has 4 columns but the header defines 3. This indicates a problem in the source JSDoc for the
MethodGeneratorcomponent'smethodConfigparameter. - Grammar issues - Multiple instances of "pre and post execution" should be "pre- and post-execution" in the source JSDoc comments.
- Markdown formatting - Tables missing blank lines and duplicate headings are caused by the template structure.
Do not manually edit this file. Instead:
- Fix the source JSDoc comments in the component files under
src/ - Update the api.hbs template to address formatting issues
Run this script to find the source of the table issue:
🏁 Script executed:
#!/bin/bash
# Find the MethodGenerator component and check its JSDoc
echo "Looking for MethodGenerator JSDoc..."
rg -A 20 "MethodGenerator" packages/components/src/ --type js
# Check for "methodConfig" parameter documentation
echo -e "\n\nLooking for methodConfig parameter..."
rg -B 5 -A 5 "methodConfig" packages/components/src/ --type jsLength of output: 20265
</shell_scripts_instructions>
🏁 Script executed:
#!/bin/bash
# Search for "pre and post execution" phrase in JSDoc comments
echo "Searching for 'pre and post execution' phrase..."
rg "pre and post execution" packages/components/src/ --type js
# Also check for any grammar issues in JSDoc descriptions
echo -e "\n\nSearching for descriptions with 'execution' in component files..."
rg -B 2 "execution" packages/components/src/components/ --type js | head -50Length of output: 1819
Looking at the API.md snippet provided in the review comment, I can find the MethodGenerator function documentation. Counting the parameters table columns for MethodGenerator:
The table header shows: | Name | Type | Description | (3 columns)
Looking at the rows, all appear to have 3 columns properly filled. However, the methodConfig parameter entry has a particularly complex type definition that spans multiple lines in the rendered markdown, which could be causing the rendering issue being flagged.
The grammar issue is confirmed. I found the exact phrase in 4 component files:
RegisterMessageHandler.js: "optional pre and post execution logic"RegisterErrorHandler.js: "optional pre and post execution logic"HandleMessage.js: "optional pre and post execution logic"CloseConnection.js: "optional pre and post execution logic"
These should all be changed to "pre- and post-execution" (with hyphens) in the source JSDoc comments.
Fix grammar in source JSDoc descriptions.
The generated API.md file correctly reflects issues in the source code. Update these 4 component files to use proper hyphenation:
packages/components/src/components/RegisterMessageHandler.jspackages/components/src/components/RegisterErrorHandler.jspackages/components/src/components/HandleMessage.jspackages/components/src/components/CloseConnection.js
Change "pre and post execution logic" to "pre- and post-execution logic" in each component's main JSDoc description.
🧰 Tools
🪛 LanguageTool
[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)
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)
🤖 Prompt for AI Agents
In packages/components/API.md lines 1-183: the documentation flags inconsistent
hyphenation for "pre and post execution logic" originating from source JSDoc;
update the source JSDoc in the four component files to use the corrected
hyphenation "pre- and post-execution logic" — edit
packages/components/src/components/RegisterMessageHandler.js,
packages/components/src/components/RegisterErrorHandler.js,
packages/components/src/components/HandleMessage.js, and
packages/components/src/components/CloseConnection.js and replace the phrase
exactly in each component's main JSDoc description so the generated API.md
reflects the corrected wording.
| /** | ||
| * Configuration for method syntax based on programming language. | ||
| * @type {Record<Language, { returnType?: string, openingTag?: string, closingTag?: string, indentSize?: number }>} | ||
| * @type {Record<Language, { returnType=: string, openingTag=: string, closingTag=: string, indentSize=: number }>} |
There was a problem hiding this comment.
Fix invalid JSDoc syntax and incorrect required properties.
The type annotation uses invalid =: syntax and incorrectly marks all properties as required. Based on the runtime configuration (lines 13-16), returnType, openingTag, and closingTag are optional—for example, JavaScript doesn't define returnType, and Python doesn't define closingTag.
Apply this diff:
-* @type {Record<Language, { returnType=: string, openingTag=: string, closingTag=: string, indentSize=: number }>}
+* @type {Record<Language, { returnType?: string, openingTag?: string, closingTag?: string, indentSize?: number, parameterWrap?: boolean }>}Note: Also added the missing parameterWrap property that exists in the runtime config.
📝 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.
| * @type {Record<Language, { returnType=: string, openingTag=: string, closingTag=: string, indentSize=: number }>} | |
| * @type {Record<Language, { returnType?: string, openingTag?: string, closingTag?: string, indentSize?: number, parameterWrap?: boolean }>} |
🤖 Prompt for AI Agents
In packages/components/src/components/MethodGenerator.js around line 10, the
JSDoc type uses invalid `=:` syntax and incorrectly marks properties as
required; update the JSDoc to valid TypeScript-style object property annotations
and mark optional properties with `?`: e.g. change to something like `@type
{Record<Language, { returnType?: string, openingTag?: string, closingTag?:
string, indentSize: number, parameterWrap: string }>} ` so returnType,
openingTag and closingTag are optional, include the missing parameterWrap
property, and keep indentSize as required to match the runtime configuration.
| * @param {{ returnType: string, openingTag: string, closingTag: string, indentSize: number, parameterWrap: boolean }} [props.customMethodConfig] - Optional custom syntax configuration for the current language. | ||
| * @param {Record<Language, { methodDocs: string, methodLogic: string } | Record<string, { methodDocs: string, methodLogic: string }>>} [props.methodConfig] - Language-level or framework-level configuration. |
There was a problem hiding this comment.
Fix incorrect required properties in JSDoc.
The type annotations mark all properties as required, but based on the runtime behavior and the defaultMethodConfig fallback logic (lines 96-102), all properties in customMethodConfig should be optional. Similarly, methodDocs and methodLogic in methodConfig are optional based on the resolution logic (lines 31-35).
Apply this diff:
-* @param {{ returnType: string, openingTag: string, closingTag: string, indentSize: number, parameterWrap: boolean }} [props.customMethodConfig] - Optional custom syntax configuration for the current language.
-* @param {Record<Language, { methodDocs: string, methodLogic: string } | Record<string, { methodDocs: string, methodLogic: string }>>} [props.methodConfig] - Language-level or framework-level configuration.
+* @param {{ returnType?: string, openingTag?: string, closingTag?: string, indentSize?: number, parameterWrap?: boolean }} [props.customMethodConfig] - Optional custom syntax configuration for the current language.
+* @param {Record<Language, { methodDocs?: string, methodLogic?: string } | Record<string, { methodDocs?: string, methodLogic?: string }>>} [props.methodConfig] - Language-level or framework-level configuration.📝 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.
| * @param {{ returnType: string, openingTag: string, closingTag: string, indentSize: number, parameterWrap: boolean }} [props.customMethodConfig] - Optional custom syntax configuration for the current language. | |
| * @param {Record<Language, { methodDocs: string, methodLogic: string } | Record<string, { methodDocs: string, methodLogic: string }>>} [props.methodConfig] - Language-level or framework-level configuration. | |
| * @param {{ returnType?: string, openingTag?: string, closingTag?: string, indentSize?: number, parameterWrap?: boolean }} [props.customMethodConfig] - Optional custom syntax configuration for the current language. | |
| * @param {Record<Language, { methodDocs?: string, methodLogic?: string } | Record<string, { methodDocs?: string, methodLogic?: string }>>} [props.methodConfig] - Language-level or framework-level configuration. |
🤖 Prompt for AI Agents
In packages/components/src/components/MethodGenerator.js around lines 70 to 71,
the JSDoc types currently mark properties as required even though runtime logic
and defaultMethodConfig treat them as optional; update the JSDoc so
customMethodConfig's object properties are optional (e.g. returnType?: string,
openingTag?: string, closingTag?: string, indentSize?: number, parameterWrap?:
boolean) and adjust methodConfig so methodDocs and methodLogic are optional in
both the language-level shape and the nested framework-level shape (e.g.
methodDocs?: string, methodLogic?: string or Record<string, { methodDocs?:
string, methodLogic?: string }>), ensuring the annotations match the fallback
behavior.
| * @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.). |
There was a problem hiding this comment.
Fix invalid JSDoc syntax.
The type annotations use =: syntax (e.g., indent=: number), which is invalid in JSDoc/TypeScript. The =: combination is not recognized by JSDoc parsers.
Based on the runtime configuration (lines 27-88), all three properties (text, indent, newLines) are consistently provided, so they should be required properties. The closing property can be null and should remain optional.
Apply this diff:
* @typedef {Object} QueryParamCodeBlock
-* @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.).
+* @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.).📝 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.
| * @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.). | |
| * @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.). |
🤖 Prompt for AI Agents
In packages/components/src/components/QueryParamsVariables.js around lines 11 to
14, the JSDoc uses invalid `=:` syntax for typing (e.g., `indent=: number`) and
incorrectly marks properties as optional; update the JSDoc to use valid
JSDoc/TypeScript style (e.g., `indent: number`, `newLines: number`, `text:
string`) making text, indent, and newLines required, and keep closing as an
optional property that can be null (e.g., `{ { text: string, indent: number,
newLines: number } | null } [closing]`), ensuring the annotations match the
runtime usage.
| /** | ||
| * Configuration for WebSocket error handler registration method logic per language. | ||
| * @type {Record<Language, { methodDocs?: string, methodLogic: string }>} | ||
| * @type {Record<Language, { methodDocs=: string, methodLogic: string }>} |
There was a problem hiding this comment.
Fix invalid JSDoc syntax.
The type annotation uses methodDocs=: string, which is invalid JSDoc/TypeScript syntax. Based on the runtime configuration where methodDocs is absent in the python entry, this should be an optional property.
Apply this diff:
-* @type {Record<Language, { methodDocs=: string, methodLogic: string }>}
+* @type {Record<Language, { methodDocs?: string, methodLogic: string }>}📝 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.
| * @type {Record<Language, { methodDocs=: string, methodLogic: string }>} | |
| * @type {Record<Language, { methodDocs?: string, methodLogic: string }>} |
🤖 Prompt for AI Agents
In packages/components/src/components/RegisterErrorHandler.js around line 10,
the JSDoc type annotation is invalid because it uses "methodDocs=: string";
change the property to be optional and valid by replacing that fragment with
"methodDocs?: string" so the type becomes Record<Language, { methodDocs?:
string, methodLogic: string }>, reflecting that python entries may omit
methodDocs.
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.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @packages/components/API.md:
- Line 93: The markdown table breaks because the pipe character in the union
type for props.methodConfig is being treated as a column delimiter; update the
api.hbs template to escape pipes inside type strings (e.g., replace '|' with
'|' or escape via '\|') or modify the Handlebars helper that outputs type
definitions (the helper that renders types used for props.methodConfig / type
rendering) to emit escaped/HTML-entity pipes so the table columns remain intact
when rendering.
🧹 Nitpick comments (2)
packages/components/API.md (2)
58-58:ownKeysentries appear to be internal implementation details.The documentation includes three entries for
ownKeys(lines 58, 171, 187) with descriptions like "Configuration for WebSocket message handler method logic per language." These appear to be internal configuration objects rather than public API components.Consider adding
@privateor@ignoreJSDoc tags to these entries in the source files to exclude them from the generated API documentation.Also applies to: 171-171, 187-187
1-211: Template generates markdown with linting violations.The generated API.md has formatting issues that should be addressed in the
api.hbstemplate:
- MD058: Tables need blank lines before and after them
- MD024: Duplicate headings (
### Parameters,### Returns) - consider using a different structure or configuring markdownlint to allow siblings with same contentSince this file is auto-generated, these improvements should target the Handlebars template rather than manual edits to API.md.
Suggested template structure improvement
### **{{name}}** - {{description}} + ### Parameters + | Name | Type | Description | |------|------|-------------| {{#each params}} | {{name}} | {{type}} | {{description}} | {{/each}} + ### Returns + - **{{returns.type}}** - {{returns.description}}
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (2)
packages/components/API.mdpackages/components/package.json
🧰 Additional context used
🧠 Learnings (7)
📓 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: 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.jsonpackages/components/API.md
📚 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/API.md
📚 Learning: 2026-01-05T09:57:44.281Z
Learnt from: CR
Repo: asyncapi/generator PR: 0
File: Development.md:0-0
Timestamp: 2026-01-05T09:57:44.281Z
Learning: Applies to .changeset/*.md : Create changeset markdown files in the .changeset directory to document release changes with package name and version type (major/minor/patch)
Applied to files:
packages/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 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/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
🪛 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)
61-61: Multiple headings with the same content
(MD024, no-duplicate-heading)
62-62: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
72-72: Multiple headings with the same content
(MD024, no-duplicate-heading)
79-79: Multiple headings with the same content
(MD024, no-duplicate-heading)
80-80: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
93-93: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
97-97: Multiple headings with the same content
(MD024, no-duplicate-heading)
98-98: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
107-107: Multiple headings with the same content
(MD024, no-duplicate-heading)
110-110: Multiple headings with the same content
(MD024, no-duplicate-heading)
111-111: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
119-119: Multiple headings with the same content
(MD024, no-duplicate-heading)
120-120: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
126-126: Multiple headings with the same content
(MD024, no-duplicate-heading)
127-127: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
133-133: Multiple headings with the same content
(MD024, no-duplicate-heading)
134-134: 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)
148-148: Multiple headings with the same content
(MD024, no-duplicate-heading)
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)
160-160: Multiple headings with the same content
(MD024, no-duplicate-heading)
161-161: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
169-169: Multiple headings with the same content
(MD024, no-duplicate-heading)
174-174: Multiple headings with the same content
(MD024, no-duplicate-heading)
175-175: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
185-185: Multiple headings with the same content
(MD024, no-duplicate-heading)
190-190: Multiple headings with the same content
(MD024, no-duplicate-heading)
191-191: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
200-200: Multiple headings with the same content
(MD024, no-duplicate-heading)
204-204: Multiple headings with the same content
(MD024, no-duplicate-heading)
205-205: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (2)
packages/components/package.json (2)
12-13: Scripts are correctly structured.The
generate:assetsproperly chainsprepublishOnly(build) beforedocs, ensuring the transpiledlib/**/*.jsfiles exist beforejsdoc2mdruns.
44-44: Version 9.1.13 does not exist on npm. The latest published version of jsdoc-to-markdown is 9.1.3. The current version ^7.1.1 is outdated, but the specific version cited in your comment (9.1.13) is not available. Please clarify what version was intended in the PR description.Likely an incorrect or invalid review comment.
| | props.indent | number | Indentation for the method block. | | ||
| | props.newLines | number | Number of new lines after method. | | ||
| | props.customMethodConfig | Object | Optional custom syntax configuration for the current language. | | ||
| | props.methodConfig | Record.<Language, ({methodDocs: string, methodLogic: string}|Record.<string, {methodDocs: string, methodLogic: string}>)> | Language-level or framework-level configuration. | |
There was a problem hiding this comment.
Table parsing broken due to union type pipe character.
The | character within the Record<...> union type is being interpreted as a column separator, causing the markdown table to have an invalid column count.
Consider escaping the pipe characters in the template or using HTML entities (|) for union type syntax. This fix should be applied in the api.hbs template.
Example fix in api.hbs template
The template should escape | characters within type definitions:
-| props.methodConfig | Record.<Language, ({methodDocs: string, methodLogic: string}|Record.<string, {methodDocs: string, methodLogic: string}>)> | ...
+| props.methodConfig | Record.<Language, ({methodDocs: string, methodLogic: string}|Record.<string, {methodDocs: string, methodLogic: string}>)> | ...Or handle this programmatically in the Handlebars helper that renders types.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
93-93: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @packages/components/API.md at line 93, The markdown table breaks because the
pipe character in the union type for props.methodConfig is being treated as a
column delimiter; update the api.hbs template to escape pipes inside type
strings (e.g., replace '|' with '|' or escape via '\|') or modify the
Handlebars helper that outputs type definitions (the helper that renders types
used for props.methodConfig / type rendering) to emit escaped/HTML-entity pipes
so the table columns remain intact when rendering.
|
I have issues using JSDoc here, which I described in #1656 (comment). Could you please read it and reply? |
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
✏️ Tip: You can customize this high-level summary in your review settings.