Open lazarljubenovic opened 3 years ago
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?
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.
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 :)
Api-Extractor may be helpful for integrating TSDoc into webdoc. It has compatibility for custom doc pipelines.
Has integration with tsdoc been considered?