Inline tsdoc comment support

Search Terms

tsdoc, comments, IDE, line sorting

Suggestion

When writing a type, sometimes you want to add more information to a field that will be surfaced in IDE autocomplete. Currently you must define them like this:

export type BoxSizeDefinition = {
  /** this is null for non-custom box sizes */
  itemCount: number | null
  size: BoxSize
  /** A description for the range of pounds included in box. */
  poundage: string
  /** price in cents of the box size */
  price: number
}

Note that the comment is above the field. This is problematic because auto-sorting linters and such will mangle the comments.

I propose also supporting inline tsdoc comments:

export type BoxSizeDefinition = {
  itemCount: number | null /** this is null for non-custom box sizes */
  size: BoxSize
  poundage: string /** A description for the range of pounds included in box. */
  price: number /** price in cents of the box size */
}

This effectively fixes the sorting problem.

Use Cases

Adding descriptive text to be shown via IDE autocomplete for fields (currently supported, but not in a sorting & codeaction-friendly way.)

Examples

See above

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start by reviewing the proposed TypeScript type examples and the stated TSDoc and IDE-autocomplete use case. Determine the parser, comment-handling, and editor behavior affected, then define tests showing that inline comments are associated with the correct fields without changing runtime output.