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.
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:
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:
@param
can be left out, so less verbose (but equally clear) syntaxCase 1
aboveMain downside:
Reference
React Styleguidist allows for a similar syntax with propTypes.