Documentation: Improve the way types are presented in the generated documentation

[gziolo]

Follow-up for #17014.

Related comment from @sirreal https://github.com/WordPress/gutenberg/pull/17014/files#r317982877:

I find the [string] syntax strange. Where does it come from?

I assume it means "optional parameter with a default value", but that only seems to vaguely align with jsdoc, where [square brackets] are used on the parameter or property names to indicate they're optional, not around the type.

To add to the confusion, in TypeScript [ string ] would mean a one-tuple of strings, or an array with a single string member, e.g. [ "foo" ] but never [] or [ "foo", "bar" ].

Response from @dsifford:

Yeah, as it stands, the way that the JSDoc is being parsed definitely results in clunky markdown for this particular case.

In JSDoc, it's pretty easy to tell the difference between optional types and single-tuple types because they are written differently.

// optional string type
/**
 * @param {string} [foo]
 */

// single tuple string type
/**
 * @param {[string]} foo
 */

So I think that you've definitely raised a valid concern with respect to how the docs are being generated.

(PS: syntax comes from here)

[paaljoachim]

Hey Greg @gziolo

I see two merged PR's. Should we close this issue?

[gziolo]

No, it's still far from perfect.

[gziolo]

It can be considered done after #28615 was landed.