microsoft / microsoft/TypeScript
Omit JSDoc type directives when emitting type declarations with documentation
- Ngôn ngữ chính
- Go
- Star
- 111k
- Fork
- 14.3k
- Merge trung bình
- 2 ngày 4 giờ
- Pull request đã merge (30 ngày)
- 132
Mô tả
### 🔍 Search Terms
"omit typedef", "exclude typedef"
### ✅ 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
When emitting type declarations from JavaScript sources, the type is already defined in the TypeScript syntax, so there's no need to copy over any `@type`, `@typedef`, or `@template` directives.
Types can also be stripped out of `@param` and `@returns` directives.
This could be taken further, by deleting JSDoc strings altogether if after stripped the types, they become empty.
### 📃 Motivating Example
For example, I have the following files:
**`css-select-adapter.js`**
```js
/**
* @param {Map} parents
* @returns {Required>['adapter']}
*/
export function createAdapter(parents) {
// …
}
```
**`tsconfig.json`**
```json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": false,
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "types/"
},
"include": ["lib/svgo-node.js", "lib/svgo.js"]
}
```
The emitted type declaration is:
```ts
/**
* @param {Map} parents
* @returns {Required>['adapter']}
*/
export function createAdapter(parents: Map): Required>["adapter"];
```
But the types defined in the JSDoc become unnecessary since it's already defined in TypeScript, so it should just be:
```ts
/**
* @param parents
* @returns
*/
export function createAdapter(parents: Map): Required>["adapter"];
```
This could be taken further, by removing the `@param`, `@returns`, and `@template` directives if all of them have no value, and removing the JSDoc outright if after removing empty directives the JSDoc becomes empty:
```ts
export function createAdapter(parents: Map): Required>["adapter"];
```
### 💻 Use Cases
In SVGO, we emit type declarations from our JSDocs. However, the type declarations can be quite noisy. It would be valuable if the output was tidied up:
1. To make them quicker/easier to human-review when needed.
2. Reduce the size of the published npm package.
We currently do not do any workarounds. We just publish the additional content to npm.
Hướng dẫn đóng góp
Hướng nghiên cứu
Tái hiện việc emit chỉ gồm declaration bằng css-select-adapter.js và tsconfig.json được nêu, sau đó truy vết cách JSDoc được đưa vào declaration đã tạo. Xác định hành vi stripping được hỗ trợ cho @type, @typedef, @template, @param và @returns, bao gồm cả thời điểm documentation rỗng bị loại bỏ; done phải bao gồm coverage cho output được đề xuất và các edge case của nó.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- javascript, typescript
- Lĩnh vực
- compilers
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100