[Feature] Full support of TsDoc tags

[skoropadas]

Description

At the moment NgDoc supports only a few TSDoc tags, we need to expand support for tags to make it clear to users which standard we support and also add documentation on how to use them. Below is a table of tags with the current and required support

Tag	Implemented	Should be implemented?	Comment
@alpha	✅ (v18)	✅	Should mark members with alpha tag
@beta	✅ (v18)	✅	Should mark members with beta tag
@decorator	❌	❌	Information about decorator collects from the code
@deprecated	✅ (v18)	✅	The name of the member will be crossed out, and display a tooltip with the tag content
@defaultValue	❌	❌	Can be implemented by request
@eventProperty	❌	❌	I don't see real use case for this tag
@example	❌	❓	We could consider it, as an option we could display another tab for API page with all examples that were found for the current entity
@experimental	✅ (v18)	✅	Should mark members with experimental tag
@inheritDoc	❌	❌	The notation has not been finalized, and I don't think we should implement it until the editors start supporting it
@internal	✅ (v18)	✅	We should hide members with such tag on API pages
@label	❌	❌	The notation has not been finalized, besides I don't think it's useful
@link	❌	❓	The notation has not been finalized. There is no need to implement it right now, NgDoc can display links via markdown or Keywords, but it would be nice to consider using this tag
@override	❌	❌	NgDoc displays overridden members, so there is no need to implement it
@packageDocumentation	❌	❌	I don't see real use case for this tag
@param	✅	❌	Fully supported
@privateRemarks	❌	❌	NgDoc should not display content after this tag
@public	❌	❌	Can be added by request, but I don't see real use case for this tag
@readonly	❌	❌	NgDoc supports readonly keyword, so there is no need to implemement this tag
@remarks	❌	❌	I would suggest to use this tag, NgDoc will join summary section with remark section of the doc because there is no need to split them at the moment, but in the future they could be displayed sepparatly on different tabs of the API page or smth like that
@returns	✅	❌	Fully supported
@sealed	❌	❌	I don't see real use case for this tag
@see	✅	❌	Supported in combination with keywords
@throws	❌	❓	I don't see a real use case for this tag, because you can use the summary to describe it, but we could consider it on request
@typeParam	❌	❓	Can be added by request with examples of usage
@virtual	❌	❌	I don't see real use case for this tag

Proposed solution

Some tags are not needed (for example, @decorator), since the documentation engine collects this information from the code, but most of them are necessary in order to display warnings or sort the documentation content.

It doesn't mean that you can't use these tags, it means that they will not be covered by NgDoc and displayed in documentation on API pages.

Alternatives considered

[dhutaryan]

By the way, I tried to use @internal and it didn't hide anything. I believe this is one of the most important tag. If you have time, please take a look at it.

[skoropadas]

@dhutaryan how did you use it? for the class/interface or their members?

[dhutaryan]

@skoropadas I used it for simple function

[HyperLife1119]

Sometimes I want to hide entire classes, interfaces:

/**
 * @internal
 */
export class MyClass { }

But I realized that @internal only supports member properties and methods.

[skoropadas]

@HyperLife1119 yes, this ticket with full support for @internal tags is gonna be done in the next major version, so you can use the internal tag and in the future version such API will be hidden

[AdrianKokot]

@skoropadas As I understand, from the table above, adding support for @link is questionable because of the unfinished RFC, but besides that, many IDEs support at least the basic syntax. I think adding support for @link would be really useful, as it's a natural way to mention different types in tscodc.

However, I can see from the source code that tags are parsed using ts-morph, I'm curious, why not use ts-doc parser provided by Microsoft (@microsoft/ts-doc)? I guess many IDEs use this package, so using it would make the ng-doc generated documentation consistent with IDE suggestions.

[skoropadas]

@AdrianKokot I initially used tsdoc to parse tags and content in comments. However, it has remained unstandardized for 2 years, so I decided to default to using jsdoc. This is sufficient for the tags supported by ngdoc at the moment.

As for the @link tag, I agree that it can be implemented with limited support (by adding support for URL and API keywords), and TSDoc can help with this.

The main issue here is that tsdoc is simply a comment parser. For example, if you write {@link my-control-library#controls.Button | the Button class}, tsdoc will simply parse it without providing information about the location of the library or the file path. On the other hand, ngdoc cannot determine this on its own because I lack this information and do not know where to obtain it, unlike an IDE. In theory, I could try to obtain it based on the tsconfig, but project configurations vary greatly, and it would be very difficult to maintain within the library.

[AdrianKokot]

Ok, thanks for the explanation. I thought that tsdoc returns paths, but you're correct, it does not. I think limited support using API Keywords would be enough as it probably covers most use cases for library documentations, and would be definitely better than not supporting it at all.

[skoropadas]

Implemented in NgDoc v18

[AdrianKokot]

@skoropadas one more question - is @example tag still considered for support?

[skoropadas]

@AdrianKokot sure we can consider that if you provide some examples of how it should be displayed

[AdrianKokot]

@skoropadas well, as far as I know, example tags can have some other text or code in probably Markdown syntax, so I think that it would be useful just to render the contents of an example block. Ie., if inside were code block, the code would be generated as it was in the markdown file. If there are multiple examples, they could be just one after another in a list, or maybe tabs. That'd be complementary to currently existing api and details sections :). Hope that makes sense.

[skoropadas]

@AdrianKokot I see, I'll try to check jsdoc/tsdoc docs again, but yeah it's not a problem to add it's more about if anyone is gonna use it.

[AdrianKokot]

@skoropadas how is @returns fully supported? If I write some text in @returns tag, I'd expect to see this text in 'returns' section, but currently (^18) only typescript type is visible