[FEATURE] Allow custom @tags in jsdoc comments

[pconnell99]

Overview of the issue

It would be useful to allow mapping arbitrary strings to tags to extract specific details out of a codebase over and above the basic tags supported for JSDocs comments (@param etc.). This could be extracted to the component/element the comment is attached to OR extracted to a separate custom page holding all these elements (think of the standard //TODO comment in an IDE that can be found and used as a guide...)

Motivation for or Use Case

We have a requirement to embed 'business logic' comments to the code. Having this extracted at compodoc run would allow the development team to see the business logic cases at a glance. Other scenarios could be forthcoming as other users see fit.

[vogloblinsky]

Do you have an example please ?, i didn't quite well understand the requirement.
Thanks

[pconnell99]

Standard jsdoc comment, but:-

/** 
A function
@param parameter {string} A parameter
@todo This text is a todo item
@businesslogic This function implements the business logic case 1
*/

And @todo and @businesslogic texts would be extracted at document generation time and either:-

1. Output inside the component documentation like a @param tag
2. Output to a separate linked 'TODO' page that displays them all per component with links back to the component they are from.

This way you can store/reflect arbitrary comment data as a user. These could be defined in config. Any user of the system could then define their own 'tags' and extract them as they see fit.

[vogloblinsky]

Ok i understand. I will add in todo for v1.1.x

I have the same approach for work/data flow during documentation. The idea is to document the path of the data inside all the layers/components of the screen, and display all paths in a dedicated page. More infos soon.

[pconnell99]

Appreciated. If you allow 'any' tag (not just @todo) you open it up to customisation for all users. Thanks.

[pconnell99]

@vogloblinsky If you'd point me in the rough direction that this would be implemented I'd be happy to take a look (and try and contribute as well if it makes sense).

[vogloblinsky]

@pconnell99
Draft of the idea here : #129

[abdel-ships-it]

This would be really useful, I am creating components that will be consumed by a content management system.

The component inputs need to be filled in by the user, and to show the appropriate UI for the appropriate inputs requires me to have context on what type of input it is.

I can obviously check whether its a number, string or boolean. But this limits me to only these three types.

Example:

Lets say I have a product-card component, which takes a productId as input and it needs to be provided by the user. Showing a product search component based on knowing its a productId would be more useful than showing a number HTML input field

TLDR

Custom JSdoc annotations will open up a world of possibilities to add more context to everything and would cover a lot of use cases.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.