doc tags ignored if they appear immediately after @example

[eladb]

:bug: Bug Report

The .jsii manifest doesn't include doc tags if they appear immediately after @example.

Repro:

/**
 * @example foo
 * @boom tag
 */
export class Foo {
}

The .jsii manifest for Foo should include the @boom doctag but it doesn't.

Affected Languages

• [x] TypeScript or Javascript
• [x] Python
• [x] Java
• [x] .NET (C#, F#, ...)

General Information

• JSII Version: <!-- Output of jsii --version --> 0.20.7

[rix0rrr]

Yep, known limitation of the TypeScript JSDoc parser.

The following:

/**
 * A function
 * @example
 * const x = require('@aws-cdk/aws-x');
 * frob(new x.Thing());
 */

Would be parsed as:

"@example" => "const x = require('"
"@aws" => "-cdk/aws-x'); frob(new x.Thing());"

So in order to properly detect the WHOLE example, I've had to absorb non-standard @tags into the @example itself.

\n is not retained in the tags that I get from symbol.getJsDocTags().

That is, the following 2 docstrings are returned in the exact same way:

/**
 * @example asdf
 * @domain .com
 */

/**
 * @example asdf@domain .com
 */

Both parse to:

[
  { "name": example", "text": "asdf" },
  { "name": domain", "text": ".com" },
]

And so I can't tell which one it was and parse it "correctly".

[eladb]

This used to work in the past so I guess something changed in how the docparser is used.

[rix0rrr]

Correct.

So in order to properly detect the WHOLE example, I've had to absorb non-standard @tags into the @example itself.

[rix0rrr]

Something we COULD do is tokenization, and absorb @-signs encountered within quotes, and treat @-signs encountered outside quotes as the start of a new tag.

Would solve most of our existing examples needs (would NOT solve the email-address-like counterexample I showed before).

But it seemed more complex than dictating that examples need to come last.

There is no way to error, because I can't tell whether the @domain is legitimately part of the example, or the start of a new tag that shouldn't have been there. If I could do that, I wouldn't need too error, because I could just parse it correctly.

[github-actions[bot]]

This issue has not received any attention in 2 years. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.