Use tsdoc instead of jsdoc

[lazarljubenovic]

Has integration with tsdoc been considered?

[ShukantPal]

Hi Lazar, Can you give me more details here? What kind of integration are you looking for? Are there tags that webdoc doesn’t support from TSDoc?

[lazarljubenovic]

My issue with allowing random JSDoc is described in this paragraph of tsdoc website:

Why can’t JSDoc be the standard? The JSDoc grammar is not rigorously specified, but rather inferred from the behavior of a particular implementation.

The idea behind tsdoc is standardization of the familiar jsdoc syntax, but with (a) TypeScript in mind, and (b) a rigorous specification in mind. As written on the website:

In many cases, sloppy parsing mostly works. Occasional malfunctions are no big deal. But when these directives determine professional website content or build output, incorrect parsing can become a serious concern.

Basically, I'd like to know if webdoc can be instructed to parse the comments with the precise way specified by tsdoc, including defining custom tags. I have high hopes for tsdoc and I wouldn't want to spend hours tweaking and checking the comments for gotchas of “well see, this jsdoc parser expects a blank line here”.

I was excited when I found a documentation generator specifically written for TypeScript, but no mention of tsdoc in the source code or in any issue got me scratching my head -- so I didn't give it a try yet.

Are there tags that webdoc doesn’t support from TSDoc?

A quick GitHub search over the repo doesn't find any mention of privateRemarks, for example.

[ShukantPal]

This makes sense. I will add rigorous support for the TSDoc standard into the roadmap.

For now, the parser allows any tag-name; however, only specific tag names will have an interpretation by default (i.e. using @privateRemarks will not do anything).

I hope the current state of the parsing will be useful to you - Tags allow one-blank line before closing the content (2 blank lines for "block" tags - @example, @classdesc):

/**
 * @tag content
 * content
 * content
 *
 * <<not added>>
 *
 * @tag2 content2
 * @tag3
 * content3
 */

It would be nice if you start using webdoc and give more feedback like this :)

[ShukantPal]

TSDoc

[sunaykomarla]

Api-Extractor may be helpful for integrating TSDoc into webdoc. It has compatibility for custom doc pipelines.