aws / aws/jsii-compiler

jsii-docgen seems to use javadoc syntax instead of tsdoc

Open
#1,498 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 [against jsii-docgen here](https://github.com/cdklabs/jsii-docgen/issues/1634)_

----

tsdoc and javadoc have slightly different syntax.

For example, tsdoc [wants a hyphen](https://tsdoc.org/pages/tags/param/) at the start of `@param` descriptions, while javadoc [does not](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDHJECF):

```
tsdoc
* @param first - The first parameter
javadoc:
* @param first The first parameter
```

I've got automated tooling to enforce tsdoc syntax, but because jsii-docgen assumes the javadoc syntax, then the documentation ends up with errant `-` characters at the start of each parameter.

Another difference is in links. For example, tsdoc [links](https://tsdoc.org/pages/tags/link/) use `|` to separate the text from the target, but javadoc [does not](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDDIECH).

```
tsdoc {@link SomeClass | click here}
javadoc {@link SomeClass click here}
```

However, the generated `remarks` sections when using `-l typescript -f json` re-print the links in javadoc syntax, even if the format is `typescript`.

### Reproduction

I've created [this repository](https://github.com/TimothyJones/jsii-docgen-issue-1633) illustrating both this issue, and the [other one I reported at the same time](https://github.com/aws/jsii-compiler/issues/1497).

*Parameter issue*:

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#L14):

```
/**
* This documents a constructor
*
* @param someParameter - this documents the parameter
*/
```

Which results in [this line in the assembly](https://github.com/TimothyJones/jsii-docgen-issue-1633/blob/main/.jsii#L69), which is from this segment:

```
"parameters": [
{
"docs": {
"summary": "- this documents the parameter."
},
"name": "someParameter",
"type": {
"primitive": "string"
}
}
]
```
(note that the `summary` inappropriately starts with `"- "`)

*`@link` issue*

Also, in the generated json documentation for typescript, [this line](https://github.com/TimothyJones/jsii-docgen-issue-1633/blob/main/docs-json/typescript.json#L52) is in javadoc syntax -

```
{@link https://github.com/cdklabs/jsii-docgen/issues/1634 this link}
```

Which seems odd, as it was originally from a properly formed tsdoc comment [here](https://github.com/TimothyJones/jsii-docgen-issue-1633/blob/main/src/index.ts#L3).

```
{@link https://github.com/cdklabs/jsii-docgen/issues/1634 | this link}
```

I'm not sure if there are other tsdoc / javadoc issues like these two, these are just the two I noticed.

Contributor guide

Open the contributing guide

Research direction

Start with the reproduction's src/index.ts and compare the generated .jsii parameter summary with docs-json/typescript.json. Trace where TSDoc parameter and link text are parsed or re-emitted, then verify that TypeScript output preserves the documented TSDoc forms without stray hyphens or Javadoc-style link separators.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.