tsdoc links crossing multiple lines are mangled
- Dominant language
- TypeScript
- Stars
- 50
- Forks
- 26
- Avg merge
- 7h 10m
- Merged PRs (30d)
- 37
Description
Version: jsii@5.5.10 (via jsii-docgen@10.5.5)
Originally opened [here](https://github.com/cdklabs/jsii-docgen/issues/1633)
### 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
### Reproduction
I've created [this repository](https://github.com/TimothyJones/jsii-docgen-issue-1633) illustrating this and another problem (about to be reported).
The relevant part for this issue is the parsing of [this line](https://github.com/TimothyJones/jsii-docgen-issue-1633/blob/main/src/index.ts#L2):
```
/**
* 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](https://github.com/TimothyJones/jsii-docgen-issue-1633/blob/main/.jsii#L54), which contains:
```
{@link https://github.com/cdklabs/jsii-docgen/issues/1633 this } * issue}
```
Contributor guide
Research direction
Start with the linked reproduction's src/index.ts and compare its generated .jsii assembly in json mode, then trace how the compiler parses the multi-line TSDoc @link. Done means the full link label remains intact and the following comment marker is excluded, matching the expected output in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100