asyncapi
Discuss duplication of JSDocs across components & potential migration to TypeScript of `@asyncapi/generator-components`
-
JSDoc Duplication: While working with different components, we have noticed that we’re duplicating JSDocs in multiple places. For example, when using the MethodGenerator across other components, the documentation is repeated instead of being shared or derived.
-
Moving to TypeScript could reduce duplication by enforcing strong typing and auto-generating documentation from type definitions. It would also improve developer experience, ensure better maintainability, and reduce bugs from untyped code.
While working on issue #1656 to generate the API.md, I noticed a lot of duplicated content, which made it difficult to navigate between components.
That’s why I introduced Handlebars templates to avoid repeating typedefs.
In generator-components, I found multiple occurrences of the same typedef, for example:
/**
- @typedef {'python' | 'javascript' | 'dart'} SupportedLanguage
- Supported programming languages for WebSocket connection method generation. */
This exact block appears in several files like HandleMessage.js, connect.js, and onError.js.
There is also a requirement to migrate the components to TypeScript. If we move to TypeScript, generating API.md becomes straightforward, and we won’t need Handlebars templates for that purpose anymore.
