docs: include underlying TypeScript types into the Documentation

[ron-debajyoti]

Description

• uses the plugin jsdoc-tsimport-plugin to properly parse jsdoc comments with import tags
• imports DiffOutput and Output of src/asyncapidiff.ts as typedefs in jsdoc comments and then utilizes them in doc generation

Related issue(s)

Fixes #47

[ron-debajyoti]

@aayushmau5 This is the current state of the solution. I had to define Output and DiffOutput as jsdoc typedefs. If you preview the generated API.md you can see that the kind is still stated as global typedef with no information from the Typescript type.

Let me see how can we improve it further.

[aayushmau5]

@ron-debajyoti See what you can do, and if the problem is still there, feel free to drop it. Like I said earlier, this task is a hard one, and possibly cannot be fixed without heavy involvement. Good luck :)

[ron-debajyoti]

@ron-debajyoti See what you can do, and if the problem is still there, feel free to drop it. Like I said earlier, this task is a hard one, and possibly cannot be fixed without heavy involvement. Good luck :)

@aayushmau5 Thanks!
I was wondering if you could look into the latest generated API.md file and point out what extra modifications/information is to be generated. I know that the typedef Diff in the document generated should typically show more information, and I'm going to try that by adding more jsdoc comments and see if I can fix that .

[ron-debajyoti]

Hey @aayushmau5 sorry if it took a while.

Here's an update of the things added in the latest commits :

• removed jsdoc2md and its build commands and configuration files.
• added typedoc and its plugins, configuration files and build commands.
• generated new docs ( present in the docs/ folder) using typedoc.
• deleted API.md and instead used docs/modules/index.md for the API information.

Do give a check and comment if any additional changes are required.

[aayushmau5]

Other than that, everything else looks pretty good. Awesome work @ron-debajyoti 🚀

[ron-debajyoti]

@aayushmau5
Here are the latest updates :

• docs/README.md can't be deleted, but I added configurations so that it's generated contents acts like a contents file wrt the doc folder. It's not the duplicate of README.md present in the root.

I did however find a bug, which I commented out above.

[aayushmau5]

@ron-debajyoti What bug are you talking about?

[ron-debajyoti]

@ron-debajyoti What bug are you talking about?

@aayushmau5 please check docs/classes/asyncapidiff.AsyncAPIDiff.md to line 52.

Defined In for all the generated doc files points to my local repository. This is seen for all the Defined In generated from the types in typedoc.
Possible solutions are :

• Generate the docs as asyncapi admin, every time the repo gets changed.
• remove this section altogether

I added a comment tagging you there but idk why you can't access it.

[aayushmau5]

@ron-debajyoti You don't need to worry about that :)

I should've told you(sorry, I didn't) but the docs will be generated by the AsyncAPI bot. So, In that case, we will probably ask you to revert your documentation changes(but keeping the configs), and once it will be merged, the new docs will be generated by the bot.

[ron-debajyoti]

So, In that case, we will probably ask you to revert your documentation changes(but keeping the configs),

Alright then @aayushmau5. Then I should delete the docs/ folder to complete the implementation right?

[aayushmau5]

Yup. Go ahead. Then I'll approve and merge :)

[ron-debajyoti]

@aayushmau5 Done. Do give a final check if required.

[ron-debajyoti]

@aayushmau5 Also I would like to say thanks a lot for guiding me throughout the process. Looking forward to more contributions in AsyncAPI !

[aayushmau5]

LGTM! 🚀 Thanks a lot! @ron-debajyoti

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[asyncapi-bot]

🎉 This PR is included in version 0.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀