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.

首先检查提议的 TypeScript 类型示例以及所述的 TSDoc 和 IDE-autocomplete 使用场景。确定受影响的 parser、注释处理和 editor 行为，然后定义测试，以表明 inline 注释会与正确的字段关联，同时不会改变 runtime output。