brightscript doc

[ZeeD]

(I'm not sure about what is the best place to put this kind of doubts, so please feel free to tell me to use another channel)

I would like to understand if there is some support for some form of documentation auto-generation looking at the source annotations, things like javadoc/doxygen/jsdoc.
on https://developer.roku.com/de-de/docs/developer-program/dev-tools/brightscript-doc.md I saw that there "was" some support, but was specifically offered by the discontinued eclipse plugin.

basically what I want are a pair of things:

1. a syntax to add comments with special tags to classes / functions / etc that are parsed by the IDE and are used to enhance the tooltips (it seems to me that now the VSCode plugin understand that the comments above are "bsdoc" but doesn't support the various @param @return tags)
2. have a (command line) tool that is able to parse my project and automatically extract the classes / functions structure and build and API document (preferably in .md format, but .html or something similar would work)

I may be wrong but it seems that there is no "pratical way" on what to use to achieve this: I saw, for example, that some projects, like rodash, relies on jsdoc to build the API documentation but to obtain this result there are basically "double comments", that are not really easy to read

[TwitchBronBron]

I haven't done research into any of this, but here's how I have been envisioning it would work over the past few months:

Enhance the the brighterscript parser to fully parse and understand BrightScriptDoc and some other popular tags from jsdoc that might be missing. It will be available in some form on the AST.

This will allow us to

• enhance the in-editor experience for hovers, definitions, etc to use this added information
• write a jsdoc plugin that will run the entire project through the brighterscript compiler, and extract/contribute those jsdoc/BrightScriptDoc items to jsdoc. No need to reinvent the wheel with a totally separate docs generator.

[ZeeD]

I think it is worth mentioning that I just found brighterscript-jsdocs-plugin that seems to check almost all the requirements!

[markwpearce]

As author of Brighterscript Jsdocs plugin , I’m happy to support any fixes needed there… however this Issue is more about parsing the docs in the context of the language parser. I think there are some huge benefits to that (like proper knowledge of parameters for hovers, etc).
The parsing of the docs in the jsdocs plugin is kind of rudimentary, but could be used as a starting point for this work.

Ideally, brighterscript would do the proper parsing, and the jsdocs plugin would simply use that information/code/functionality to let jsdocs build the HTML pages.