jsii-docgen seems to use javadoc syntax instead of tsdoc
- 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
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