RFC: less redundant syntax

[lensbart]

Hello!

First and foremost, thanks for developing this tool — looks very promising.

Proposal

When documenting my TypeScript code, I generally try to avoid redundantly retyping variable names wherever possible. For example:

// Case 1
type Input = {
  /** Description of `n` goes here */
  n: number
}

/** Description of function goes here */
export const fn = ({ n }: Input) => {
  return n ^ 2
}

// Case 2
/** Description of function goes here */
export const fn = (
  /** Description of `n` goes here */
  n: number
) => {
  return n ^ 2
}

The Description of n goes here does not currently seem to be retrieved by tsdoc. Is this something that you would consider putting on the roadmap?

I see several upsides:

• The parameter description is colocated with its name and type for easier visual grepping
• It is not needed to retype the variable name anymore, avoiding potential mismatch when refactoring
• @param can be left out, so less verbose (but equally clear) syntax
• Works especially well (is visually pleasing) for functions with a destructured object as argument, cf. Case 1 above

Main downside:

• Function declaration with non-destructured argument(s) (cf. Case 2 above) gets a bit more clumsy for large comment blocks, which may look unfamiliar. Therefore I would propose to keep this as an optional (and perhaps recommended) extension to the current way of working, and not as a replacement.

Reference

React Styleguidist allows for a similar syntax with propTypes.