tsickle's JSDoc parser / Closure Compiler syntax

[evmar]

[feel free to just close this if not relevant, but I noticed other bugs similar to this]

tsickle is our glue from TypeScript syntax into Closure Compiler syntax. Closure uses JSDoc annotations heavily with its own interpretations and parser, and tsickle understands a subset of that syntax so we can write TypeScript code and pass modified JSDoc comments through to Closure Compiler. (This also relates to issue #23 a bit.)

I don't know if any of this is relevant to your project, but if you're looking to answer any questions about which tags are allowed by Closure Compiler, or our what best guesses at how to parse patterns found in actual source text, you might find https://github.com/angular/tsickle/blob/master/src/jsdoc.ts interesting.

Also, I'd be happy to answer any questions you have in this area. We (tsickle) would be happy to outsource our JSDoc parsing to a standard library like this as long as it parsed all the syntaxes we care about.

With only a few minutes of thought I think the main points worth mentioning are:

1. Closure Compiler uses curly braces in some places to mark parameterized tags, such as

/**
 * @suppress {checkFoo,checkBar} plain text goes here
 */

Where we want to be able to get at the list of ['checkFoo', 'checkBar'] programmatically.

2. Closure Compiler has special handling of @license, in that

/**
 * @license text that spans
 * multiple lines
 */

parses as a multi-line @license tag.

[octogonz]

Cool, thanks very much for providing this reference! I am on vacation in July, but when I get back to work I'll definitely go through this tag set and compare it against the TSDoc core tags to see if there's anything we can align better.

We (tsickle) would be happy to outsource our JSDoc parsing to a standard library like this as long as it parsed all the syntaxes we care about.

The base tsdoc parser is nearly finished, but I need to do a couple more PRs before the external API for consumers will be ready. Once that's in, I'll follow up, and we can see how our API compares to the requirements/expectations for the tsickle parser. The starting point will be a TextRange input corresponding to an already extracted /** */ comment, similar to what you'd get from the TypeScript compiler API. The output will be a tree of DocNode subclasses.

1. Closure Compiler uses curly braces in some places to mark parameterized tags, such as

/**
 * @suppress {checkFoo,checkBar} plain text goes here
 */

This should be pretty easy to accommodate. The @param syntax uses a similar delimiter in JSDoc. This isn't needed in TypeScript, but we will need to handle it correctly for the lax mode.

2. Closure Compiler has special handling of @license, in that

/**
* @license text that spans
* multiple lines
*/

parses as a multi-line @license tag.

The TSDoc parser models block tags as standalone nodes that optionally may begin a region of multiline rich text. So this one will probably "just work" without any special accommodations.