microsoft / microsoft/TypeScript
Add initializer property to JSDocParameterTag node
还没有人认领这个 Issue。
- 主要语言
- Go
- 星标
- 111k
- 派生
- 14.3k
- 平均合并
- 2 天 4 小时
- 30 天内合并 PR
- 132
描述
### 🔍 Search Terms
param, parameter, argument, jsdoc, initializer, default value, parameter
### ✅ Viability Checklist
- [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [x] This wouldn't change the runtime behavior of existing JavaScript code
- [x] This could be implemented without emitting different JS based on the types of the expressions
- [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [x] 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:
```js
/**
* @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:
```ts
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.
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
调研方向
定位 TypeScript 编译器中的 JSDocParameterTag 定义和现有的 Parameter initializer 处理逻辑,然后跟踪 JSDoc 参数默认值的解析位置。检查相关的编译器测试中对 JSDoc AST 属性的覆盖,并添加测试覆盖以表明解析后的默认值会作为可选 initializer 暴露出来。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- javascript, typescript
- 领域
- compilers
- Issue 类型
- 功能
- 难度
- 3/5
- 预计耗时
- 1-2 天
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100