jsii-docgen seems to use javadoc syntax instead of tsdoc

[TimothyJones]

Version: [email protected] (via [email protected])

Originally opened against jsii-docgen here

---

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.

Reproduction

I've created this repository illustrating both this issue, and the other one I reported at the same time.

Parameter issue:

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 "- ")

@link issue

Also, 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 tsdoc / javadoc issues like these two, these are just the two I noticed.