jsii-docgen seems to use javadoc syntax instead of tsdoc

[TimothyJones]

tsdoc and javadoc have slightly different syntax.

For example, tsdoc wants a hyphen at the start of @param descriptions, while javadoc does not:

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 use | to separate the text from the target, but javadoc does not.

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.

[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 this issue, and the other one I reported at the same time.

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

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

Which results in this line in the assembly, which is from this segment:

        "parameters": [
          {
            "docs": {
              "summary": "- this documents the parameter."
            },
            "name": "someParameter",
            "type": {
              "primitive": "string"
            }
          }
        ]

(note that the summary inappropriately starts with "- ")

[TimothyJones]

Oh, I forgot to include the repro for the link issue - in the generated json documentation for typescript, this line 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.

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

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

[TimothyJones]

Also, let me know if you want me to reopen these issues somewhere else.

[mrgrain]

Also, let me know if you want me to reopen these issues somewhere else.

That's a great reproduction. Both look like issues with aws/jsii-compiler.
Thank you that would be great if you could reopen them over there.

But no promises on priority. I'm pretty sure jsii doesn't parse these things itself but relies on other tools. So we might need to look into them.

[TimothyJones]

Thanks! Opened aws/jsii-compiler#1498 to track this.