aws / aws/jsii-compiler

tsdoc links crossing multiple lines are mangled

Open
#1,497 0 comments 0 reactions 0 assignees View on GitHub
bug p2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.