Preserve property comment and insert @default value, if provided

[jednano]

Search Terms

default initial initializer value preserve comment tsdoc type options option bag

Suggestion

As the title suggests, insert a @default comment to the TSDoc AST if an initializer is provided, preserving the original comment.

Use Cases

I have a default value for an option and I want the consumer of the library to know what the default value is.

Examples

interface Options {
  /**
   * The server host.
   */
  host?: string;
  port?: number;
}

function serve({ host = 'localhost', port }: Options) {
  return { host, port };
}

Playground

Hovering over host in the return statement shows the following in vscode:

Not only is the TSDoc comment lost for this property, but it could furthermore be improved if @default "localhost" were added to it, seeing as that information is available in this context.

It should look like this:

Much ❤️ for the TS team!

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.

[MartinJohns]

I think this is a duplicate of #32392.

[jednano]

I think this is a duplicate of #32392.

It’s related, but not the same, because that issue says nothing about @default comments.

[jednano]

@RyanCavanaugh I've provided a detailed example of the scenarios that are missing tooltip information below 👇🏻

interface FooOptions {
  /**
   * original bar
   * @default 'original' original
   */
  bar?: string;
  /**
   * original baz
   * @default 'original' original
   */
  baz?: string;
}

{
  function foo({ bar = 'original' } = {}) {
    return bar;
  }

  foo({
    /**
     * Actual Tooltip:
     *   (property) bar?: string | undefined
     * Expected Tooltip:
     *   (property) bar?: string | undefined
     *   _@default — 'original' original_
     */
    bar: 'x'
  });
}

{
  interface ExtendedFooOptions extends FooOptions {
    /**
     * extended bar
     * @default 'extended' extended
     */
    bar?: string;
  }

  function foo({
    /**
     * Actual Tooltip:
     *   var bar: string
     * Expected Tooltip:
     *   var bar: string
     *   extended bar
     *   _@default — 'overridden' extended_
     */
    bar = 'overridden',
    /**
     * Actual Tooltip:
     *   var baz: string
     * Expected Tooltip:
     *   var baz: string
     *   original baz
     *   _@default — 'overridden' original_
     */
    baz = 'overridden'
  }: ExtendedFooOptions = {}) {
    return [
      /**
       * Actual Tooltip:
       *   var bar: string
       * Expected Tooltip:
       *   var bar: string
       *   extended bar
       *   _@default — 'overridden' extended_
       */
      bar,
      /**
       * Actual Tooltip:
       *   var baz: string
       * Expected Tooltip:
       *   var baz: string
       *   original baz
       *   _@default — 'overridden' original_
       */
      baz
    ] as const;
  }

  foo({
    /**
     * Actual Tooltip:
     *   (property) ExtendedFooOptions.bar?: string | undefined
     *   extended bar
     *   @default — 'extended'
     * Expected Tooltip:
     *   var bar: string
     *   extended bar
     *   _@default — 'overridden' extended_
     */
    bar: 'x',
    /**
     * Actual Tooltip:
     *   var baz: string
     * Expected Tooltip:
     *   var baz: string
     *   original baz
     *   _@default — 'overridden' original_
     */
    baz: 'y'
  });
}

Playground

[Danielku15]

I would also have a strong interest in providing default values in my TSdocs (d.ts) shipped in my package. I have a wide range of options in my settings classes and want to let people know the default values (in the IDE, but also when generating my website with the API docs).

My Input:

class MySettings {
   /**
    * Description of optionA.
    */
   public optionA:string = 'default string';
   /**
    * Description of optionB.
    */
   public optionB:number = 1.2;
   /**
    * Description of optionC.
    */
   public optionC:MyEnum = MyEnum.Value; 
}

In my d.ts output I'd like to have something like:

declare class MySettings {
   /**
    * Description of optionA.
    * @default `'default string'`
    */
   public optionA:string;
   /**
    * Description of optionB.
    * @default `1.2`
    */
   public optionB:number;
   /**
    * Description of optionC.
    * @default `MyEnum.Value`
    */
   public optionC:MyEnum; 
}

Looking at the interest of and age of this issue, I fear it might never come as an official feature. So I'm wondering: Is there maybe a good way customize the produced output and inject such tags? e.g. via the typescript compiler API using transformers? Some hints on where to adapt/extend the compiler would be very helpful for that.