add jsdocs for readme components

Author: batchu5

packages/components/docs/API.md

@@ -10,7 +10,7 @@
     "lint": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore .",
     "lint:fix": "eslint --max-warnings 0 --config ../../.eslintrc --ignore-path ../../.eslintignore . --fix",
     "generate:assets": "npm run prepublishOnly && npm run docs",
-    "docs": "jsdoc2md --helper \"jsdoc2md-helpers/jsdoc-helper.js\" --template \"jsdoc2md-handlebars/api.hbs\" \"./lib/**/*.js\" > docs/API.md"
+    "docs": "jsdoc2md --helper \"jsdoc2md-helpers/jsdoc-helper.js\" --template \"jsdoc2md-handlebars/api.hbs\" \"./lib/**/*.js\" \"./lib/**/readme/*.js\" > docs/API.md"
   },
   "files": [
     "lib/**",

packages/components/package.json

@@ -2,6 +2,30 @@ import { Text } from '@asyncapi/generator-react-sdk';
 import OperationHeader from './OperationHeader';
 import MessageExamples from './MessageExamples';
 
+/**
+ * Renders a list of AsyncAPI operations with their headers and message examples.
+ * @param {Object} props - Component Props
+ * @param {object} props.operations - Array of AsyncAPI Operation objects.
+ * @returns {JSX.Element} A Component containing rendered operations, or null if no operations are provided
+ * 
+ * @example
+ * import path from "path";
+ * import { Parser, fromFile } from "@asyncapi/parser";
+ * 
+ * async function renderAvailableOperations(){
+ *   const parser = new Parser();
+ *   const asyncapi_websocket_query = path.resolve(__dirname, '../../../helpers/test/__fixtures__/asyncapi-websocket-query.yml');
+ * 
+ *   //parse the AsyncAPI document
+ *   const parseResult = await fromFile(parser, asyncapi_websocket_query).parse();
+ *   const parsedAsyncAPIDocument = parseResult.document;
+ * 
+ *   return (
+ *    <AvailableOperations operations={parsedAsyncAPIDocument.operations().all()} />
+ *   )    
+ * }
+ */
+
 export function AvailableOperations({ operations }) {
   if (!operations || operations.length === 0) {
     return null;

packages/components/src/components/readme/AvailableOperations.js

@@ -11,6 +11,19 @@ const methodConfig = {
   },
 };
 
+/**
+ * Renders a list of core WebSocket client methods for a given target language.
+ * @param {Object} props - Component props 
+ * @param {string} props.language - Target language used to select method names.
+ * @returns {JSX.Element} A Text Component that contains a list of core client methods.
+ * 
+ * @example
+ * const language = "javascript";
+ * return (
+ *   <CoreMethods language={language} />
+ * )
+ */
+
 export function CoreMethods({ language }) {
   const config = methodConfig[language];
   const { msgHandler, errHandler } = config;

packages/components/src/components/readme/CoreMethods.js

@@ -5,6 +5,19 @@ const installCommands = {
   javascript: 'npm install',
 };
 
+/**
+ * Renders the Installation Command for a given language.
+ * @param {Object} props - Component Props 
+ * @param {string} props.language - The programming language for which to generate Installation Command.
+ * @returns {JSX.Element} A Text Component that contains Installation Command.
+ * 
+ * @example
+ * const language = "javascript";
+ * return (
+ *   <Installation language={language} />
+ * )
+ */
+
 export function Installation({ language }) {
   const command = installCommands[language];
   return (

packages/components/src/components/readme/Installation.js

@@ -35,8 +35,35 @@ client.${opId}(${JSON.stringify(payload, null, 2)})
 \`\`\`
 `;
 }
+/**
+ * Renders Message Examples of a given AsyncAPI operation.
+ * 
+ * @param {Object} props - Component Props
+ * @param {object} props.operation - An AsyncAPI Operation object.
+ * @returns {JSX.Element} A Text Component that contains message examples.
+ * 
+ * @example
+ * import path from "path";
+ * import { Parser, fromFile } from "@asyncapi/parser";
+ * 
+ * async function renderMessageExamples(){
+ *   const parser = new Parser();
+ *   const asyncapi_websocket_query = path.resolve(__dirname, '../../../helpers/test/__fixtures__/asyncapi-websocket-query.yml');
+ * 
+ *   //parse the AsyncAPI document
+ *   const parseResult = await fromFile(parser, asyncapi_websocket_query).parse();
+ *   const parsedAsyncAPIDocument = parseResult.document;
+ *   const operations = parsedAsyncAPIDocument.operations().all();
+ * 
+ *   operations.map((operation) => {
+ *      return (
+ *        <MessageExamples operation={operation} />
+ *      )    
+ *   })  
+ * }
+ */
 
-export default function MessageExamples({ operation }) {
+export function MessageExamples({ operation }) {
   const operationId = operation.id();
   const messages = getOperationMessages(operation) || [];
 

packages/components/src/components/readme/MessageExamples.js

@@ -1,6 +1,34 @@
 import { Text } from '@asyncapi/generator-react-sdk';
 
-export default function OperationHeader({ operation }) {
+/**
+ * Renders a header section for a single AsyncAPI operation.
+ * @param {Object} props - Component properties.
+ * @param {object} props.operation - An AsyncAPI Operation object.
+ * @returns {JSX.Element} A Text Component that contains formatted operation header.
+ * 
+ * @example
+ * import path from "path";
+ * import { Parser, fromFile } from "@asyncapi/parser";
+ * 
+ * async function renderOperationHeader(){
+ *   const parser = new Parser();
+ *   const asyncapi_websocket_query = path.resolve(__dirname, '../../../helpers/test/__fixtures__/asyncapi-websocket-query.yml');
+ * 
+ *   //parse the AsyncAPI document
+ *   const parseResult = await fromFile(parser, asyncapi_websocket_query).parse();
+ *   const parsedAsyncAPIDocument = parseResult.document;
+ *   const operations = parsedAsyncAPIDocument.operations().all();
+ * 
+ *   operations.map((operation) => {
+ *      return (
+ *        <OperationHeader operation={operation} />
+ *      )    
+ *   }
+ * }
+ * 
+ */
+
+export function OperationHeader({ operation }) {
   const operationId = operation.id();
   const summary = operation.hasSummary() ? operation.summary() : '';
   const description = operation.hasDescription() ? `\n${operation.description()}` : '';

packages/components/src/components/readme/OperationHeader.js

@@ -1,5 +1,41 @@
 import { Text } from '@asyncapi/generator-react-sdk';
 
+/**
+ * Renders an overview section for a WebSocket client.
+ * Displays the API description, version, and server URL.
+ * 
+ * @param {Object} props - Component props 
+ * @param {object} props.info - Info object from the AsyncAPI document.
+ * @param {string} props.title - Title from the AsyncAPI document.
+ * @param {string} props.serverUrl - ServerUrl from a specific server from the AsyncAPI document.
+ * @returns {JSX.Element} A Text Component that contains the Overview of a Websocket client.
+ * 
+ * @example
+ *  
+ * import path from "path";
+ * import { Parser, fromFile } from "@asyncapi/parser";
+ * import { getServer, getServerUrl } from '@asyncapi/generator-helpers';
+ * 
+ * async function renderOverview(){
+ *   const parser = new Parser();
+ *   const asyncapi_websocket_query = path.resolve(__dirname, '../../../helpers/test/__fixtures__/asyncapi-websocket-query.yml');
+ * 
+ *   //parse the AsyncAPI document
+ *   const parseResult = await fromFile(parser, asyncapi_websocket_query).parse();
+ *   const parsedAsyncAPIDocument = parseResult.document;
+ * 
+ *   const info = parsedAsyncAPIDocument.info();
+ *   const title = info.title();
+ *   const server = getServer(parsedAsyncAPIDocument.servers(), 'withoutPathName');
+ *   const serverUrl = getServerUrl(server);
+ * 
+ *   return (
+ *      <Overview info={info} title={title} serverUrl={serverUrl} />
+ *   )
+ * }
+ * 
+ */
+
 export function Overview({ info, title, serverUrl }) {
   return (
     <Text newLines={2}>

packages/components/src/components/readme/Overview.js

@@ -6,6 +6,44 @@ import { Usage } from './Usage';
 import { CoreMethods } from './CoreMethods';
 import { AvailableOperations } from './AvailableOperations';
 
+/**
+ * Renders a README.md file for a given AsyncAPI document.
+ * 
+ * Composes multiple sections (overview, installation, usage, core methods,
+ * and available operations) into a single File component based on the
+ * provided AsyncAPI document, generator parameters, and target language.
+ * @param {Object} props - Component props
+ * @param {string} props.asyncapi - Parsed AsyncAPI document instance.
+ * @param {object} props.params - Generator parameters used to customize output 
+ * @param {string} props.language - Target language used to render language-specific sections.
+ * @returns {JSX.Element} A File component representing the generated README.md.
+ * 
+ * @example
+ * import path from "path";
+ * import { Parser, fromFile } from "@asyncapi/parser";
+ * import { buildParams } from '@asyncapi/generator-helpers';
+ * async function renderReadme(){
+ *   const parser = new Parser();
+ *   const asyncapi_websocket_query = path.resolve(__dirname, '../../../helpers/test/__fixtures__/asyncapi-websocket-query.yml');
+ * 
+ *   // parse the AsyncAPI document
+ *   const parseResult = await fromFile(parser, asyncapi_websocket_query).parse();
+ *   const parsedAsyncAPIDocument = parseResult.document;
+ *   const language = "javascript";
+ *   const config = { clientFileName: 'myClient.js' };
+ *   const params = buildParams('javascript', config, 'echoServer');
+ *   
+ *   return (
+ *     <Readme 
+ *       asyncapi={parsedAsyncAPIDocument} 
+ *       params={params} 
+ *       language={language}
+ *     />
+ *   )
+ * }
+ * 
+ */
+
 export function Readme({ asyncapi, params, language }) {
   const server = getServer(asyncapi.servers(), params.server);
   const info = getInfo(asyncapi);

packages/components/src/components/readme/Readme.js

@@ -30,6 +30,29 @@ main();
 `,
 };
 
+/**
+ * Renders a usage example snippet for a generated client in a given language.
+ * @param {Object} props - Component props
+ * @param {string} props.clientName - The Exported name of the client.
+ * @param {string} props.clientFileName -  The file name where the client is defined.
+ * @param {string} props.language - The target language for which to render the usage snippet
+ * @returns {JSX.Element} A Text component containing a formatted usage example snippet.
+ * 
+ * @example
+ * const clientName = "MyClient";
+ * const clientFileName = "myClient.js";
+ * const language = "javascript";
+ * 
+ * return (
+ *   <Usage 
+ *      clientName={clientName} 
+ *      clientFileName={clientFileName} 
+ *      language={language}
+ *   />
+ * )
+ * 
+ * 
+ */
 export function Usage({ clientName, clientFileName, language }) {
   const snippetFn = usageConfig[language];
   const snippet = snippetFn(clientName, clientFileName);