Enhance API docs with information about results of code generation with generateFromString using entrypoint

[derberg]

Reason/Context

The problem is described here asyncapi-archived-repos/playground#79. It must be clear that returned data is not content but an object with content and metadata + what is this metadata, and that it is only with React renderer.

Description

Probably JSDoc must be only updated. Of course, some additional section in the readme would be also welcomed 😄

[jonaslagoni]

Quick note it might actually not be a feature but a bug. Think the generateFromString should always return the content as is regardless of whether it is a Nunjucks or React template.

If it is the case remember to change the playground afterwards.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[derberg]

it is still valid, not JSDoc fix but bug fix but still easy to do.
No need to followup with playground as it is not used anymore

[starlightknown]

Hi, I would like to take on this issue. A little guidance might be needed, I saw the playground PR and got some context.

[derberg]

I think it would be enough to just extend JSDoc of this function and explain that if entrypoint option is passed then the following object is returned => https://github.com/asyncapi/generator-react-sdk/blob/master/src/renderer/template.ts#L80

@magicmatatjahu @jonaslagoni thoughts?

@starlightknown did you edit JSDoc before? do you need support in explaining how to make changes locally and test if they work as expected?

[starlightknown]

No, I haven't done it before and yes I'll need some help please

[derberg]

@starlightknown happy to help, no worries. Let's just make sure folks @magicmatatjahu @jonaslagoni agree with the fix that needs to be applied

[jonaslagoni]

Sounds good to me 👍

[derberg]

@starlightknown looks like this one is ready to go, still interested?

[lumenCodes]

Hello @derberg please I want to tweet about this issue so first-time contributors can check it out.

[derberg]

@lumenCodes feel free 👍🏼

[lumenCodes]

Done

[Jagrutiti]

Hey,

Is this still issue open to work?

There are discussions. But no PRs.

[Jagrutiti]

In the description it is written:

Probably JSDoc must be only updated

Could you share the link of JSDoc?

[derberg]

@Jagrutiti hey, this is still valid.
JSDoc is part of the code, and then API.md file is generated from it.

This is a return definition that needs to be more specific -> https://github.com/asyncapi/generator/blob/master/lib/generator.js#L256. and https://github.com/asyncapi/generator/blob/master/lib/generator.js#L164

so basically in case entrypoint is used and output flag is set to string then generator instead of generating folders and files on a drive, it returns object like -> https://github.com/asyncapi/generator-react-sdk/blob/master/src/renderer/template.ts#L80 so generation result must be extracted from content property.

I personally do not know how to best do it with JSDoc, you need to have a look at their docs.
It might be something like @return {Promise<TemplateRenderResult|undefined>} with some additional explanation. But TemplateRenderResult type would have to be there too:

    /**
     * @typedef TemplateRenderMetadata
     * @type {object}
     * @property {string} fileName
     * @property {string} permissions
     */

    /**
     * @typedef TemplateRenderResult
     * @type {object}
     * @property {string} content
     * @property {TemplateRenderMetadata} metadata
     */

@jonaslagoni any better suggestions?

[jonaslagoni]

Not really unless we want to convert the entire project into typescript 😄 So sounds good 👍

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[chinma-yyy]

Hey @derberg Could you once review the PR?

[derberg]

unless we want to convert the entire project into typescript

burn 😛

Could you once review the PR?

on it, sorry for delay 🙏🏼

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[lmgyuan]

Can I take on this issue?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[derberg]

@lmgyuan you can take up this one if you want