Add initializer property to JSDocParameterTag node

[AlfonzAlfonz]

🔍 Search Terms

param, parameter, argument, jsdoc, initializer, default value, parameter

✅ Viability Checklist

• 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, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Add an optional initializer property to the JSDocParameterTag, which will contain the default value of the param tag.

For a function:

/**
 * @param {string} [p="test"] - An optional param with a default value
 */
const abc = (p) => {};

The initializer property will be test.

This is a parity change with the Parameter node, which has initializer property for initializer in the parameter declaration:

const abc = (p: string = "test") => {};

📃 Motivating Example

Adding the initializer property to the JSDocParameterTag makes it possible to indicate default value of any overloaded function or function declaration, which was previously impossible. This adds the same property which was previously only available on the Parameter node. So IDEs or other tools built on TypeScript compiler now can easily communicate the default value of the parameter.

Since the default value of the parameter is currently already parsed, it should by trivial to just add it to the node as a new property and shouldn’t cause any performance issues.

💻 Use Cases

1. What do you want to use this for?
   This can be used by IDEs or other tooling (such as documentation generators) to show default value of the parameter, which rely on TypeScript compiler.
   In my use case I’m building a documentation generator which outputs parameter table for functions with types, default values and descriptions. For default values I’m using the initializer of the function and if it’s not specified I would like the default value from the param tag.

2. What shortcomings exist with current approaches?

   There is no way how to access default values of overloaded methods or method declarations. This is also true for overloaded methods where initializer is not permitted in the parameter itself.

3. What workarounds are you using in the meantime?

   The tools which want to use this have to parse the jsdoc parameter themselves.

If this issue gets approved I would gladly submit a PR for this.

[sandersn]

A couple of questions that I'd like to see answered about this:

1. Is this intended more for Javascript than Typescript? Both about equally?
2. Is this intended to improve the language service? Generated documentation?
3. Do you have evidence or particular uses where people prefer to put the initialiser in JSDoc instead of the actual parameter? That's the reason that @param doesn't currently parse initialisers. It's been 8 years since I did the analysis, but I think it showed that param tag initialisers are not used much.

Specifically, you mention overloads. Can you give an example of how this helps with overloads? The current example looks like it would be better written as:

/**
 * @param [p] - An optional param with a default value
 */
const abc = (p = "test") => {};

In general, Typescript supports JSDoc tags in order to express things are not possible in JS. It's not trying to make each tag the complete mirror of the equivalent TS node.

[AlfonzAlfonz]

The use case with the overloaded method is that, there is currently no way how to indicate that an optional parameter has some optional value. Since the initialization is implemented manually it doesn't make sense to specify it in the method declaration, but it still can be useful to specify it in the JSDoc comment:

class FileDownloader {
  // This is currently not possible and will not be parsed.
	/** @param [baseUrl='https://example.com'] */
	public async download(path: string, baseUrl?: string): Promise<Response>;
	public async download(url: URL): Promise<Response>;
	public async download(...args: [path: string, baseUrl?: string] | [URL]) {
		const url = args.length === 2 ? new URL(args[0], args[1] ?? 'https://example.com') : args[0];
		/* ... */
	}
}

This could be also used in declaration files, because the initializer is removed and replaced with an optional files:

// FileDownloader.d.ts

class FileDownloader {

    /**
     * @param [baseUrl='https://example.com'] Optional server URL where application files are located.
     */
    download(path: string, baseUrl?: string): Promise<void>;
}

All of those use cases are kind of possible right now, because it does not break the parsing of the @param, but tool which leverage TypeScript Compiler API are not able to leverage this value, because it is discarded.

Some tools, which do not fully rely on TypeScript Compiler, such as WebStorm, do parse the initializer value. So it does have some potential use.

So to answer your questions:

1. On a second look, this looks primarily useful for TypeScript and not JavaScript
2. Yes, IDEs may serve additional information to the user and this also can be used for other tools, such as documentation generator that can extract additional information from the source code.
3. I would say that the main use cases are with the overloaded methods/declaration I mentioned above.

I hope this anwers you questions.