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.
|
WalkthroughAdds generated API documentation support (API.md + Handlebars template and docs script), includes jsdoc-to-markdown devDependency, and updates JSDoc typedefs/aliases across many components; changes are documentation and JSDoc/type-annotation focused with no runtime logic changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (6)
🚧 Files skipped from review as they are similar to previous changes (5)
🔇 Additional comments (2)
Tip 📝 Customizable high-level summaries are now available in beta!You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.
Example instruction:
Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later. 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.
| "@babel/preset-react": "^7.25.9", | ||
| "jest": "^27.3.1", | ||
| "jest-esm-transformer": "^1.0.0", | ||
| "jsdoc-to-markdown": "^9.1.3" |
There was a problem hiding this comment.
🧩 Analysis chain
Verify jsdoc-to-markdown v9.1.3 is actively maintained and free from vulnerabilities.
The version pinning strategy (caret ^9.1.3) allows patch and minor updates. Ensure this version resolves the JSDoc type parsing issue mentioned in the PR (optional-property marker ? in Record types) and is free from security advisories.
🌐 Web query:
Does jsdoc-to-markdown v9.1.3 support optional property markers in JSDoc Record types, and are there known security advisories for this version?
💡 Result:
Short answer:
-
No — jsdoc-to-markdown (v9.1.3) does not add special support for "question‑mark" optional property markers inside JSDoc record type syntax; JSDoc/Closure-style record types generally require either the square-bracket property form ([@Property {T} [name]]) or an explicit union with undefined (e.g. T|undefined). (jsdoc.app)
-
No known public security advisories specific to jsdoc-to-markdown v9.1.3 were reported in major vulnerability trackers (Snyk / npm metadata) at the time of checking. (security.snyk.io)
If you want, I can show an example JSDoc workaround (square-bracket/@Property or |undefined) and a quick scan of your project for indirect dependency advisories.
Citations:
- 1: https://jsdoc.app/tags-property?utm_source=openai
- 2: https://security.snyk.io/package/npm/jsdoc-to-markdown/1.3.3?utm_source=openai
Dependency version does not support the stated JSDoc optional-property marker feature.
Web verification confirms that jsdoc-to-markdown v9.1.3 does not support optional property markers (?) in JSDoc Record types—the standard workarounds require square-bracket syntax or explicit undefined unions instead. If the PR intends to resolve the optional-property marker parsing issue via this dependency upgrade, v9.1.3 will not achieve that. No security advisories were found for this version.
🤖 Prompt for AI Agents
In packages/components/package.json at line 43, the dependency
jsdoc-to-markdown@^9.1.3 does not support JSDoc Record optional-property marker
(`?`), so the upgrade will not fix parsing of `?` in Record types; either update
the dependency to a version that explicitly adds support for `?` (verify release
notes/changelog before bumping) or revert this change and instead update the
source JSDoc to use supported alternatives (square-bracket optional syntax or
explicit `| undefined` unions) and add a comment in the package.json/change log
explaining why the dependency was not upgraded.
There was a problem hiding this comment.
so should i replace the '?' mark with sqaure brackets
|
2 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.