tsdoc links crossing multiple lines are mangled

[TimothyJones]

Version: [email protected]

Summary

When using jsii-docgen in json mode, multi-line @link elements are mangled.

Description

I have some documentation like the following (note the multi-line tsdoc @link in the first line):

/**
 * Matches the content of a variable that comes from a state. See {@link https://case.contract-testing.io/docs/defining-contracts/state-definitions | state
 * definitions}
 * and {@link https://case.contract-testing.io/docs/reference/state-handlers | state handlers} for
 * more details.
 *
 * @public
 */
export class StateVariable extends AnyMatcher {
   /* ... */
}

The generated remarks section in the json doc is mangled - it assumed the first link finishes at the end of the first line, so the text link ends state} * definitions }.

Expected behaviour

The parsed link appears as:

See {@link https://case.contract-testing.io/docs/defining-contracts/state-definitions state definitions}

Actual behaviour

The link appears as

See {@link https://case.contract-testing.io/docs/defining-contracts/state-definitions state} * definitions}

Note that:

• The link ends twice, once after state, and again after definitions
• The * from the next line is erroneously included

[mrgrain]

jsii-docgen doesn't parse your TS code, instead it reads from a pre build jsii assembly file (usually .jsii).

Can you please post the relevant section from your jsii assembly. If it's already wrong in the assembly, the issue is with aws/jsii-compiler and not jsii-docgen. (And because these repos live in a different organizations we unfortunately cannot move the issue.)

[TimothyJones]

Sure thing! I've created this repository illustrating both problems.

The relevant part for this issue is the parsing of this line:

/**
 * This class reproduces the bugs at {@link https://github.com/cdklabs/jsii-docgen/issues/1633 | this 
 * issue} 

Which results in this line in the assembly, which contains:

  {@link https://github.com/cdklabs/jsii-docgen/issues/1633 this } * issue} 

[TimothyJones]

Issue opened on the source repository here: aws/jsii-compiler#1497

[mrgrain]

Thank you!