microsoft / microsoft/TypeScript

Omit JSDoc type directives when emitting type declarations with documentation

Đang mở
#61,664 0 bình luận 1 reaction 0 người được giao Xem trên GitHub
Awaiting More Feedback Suggestion
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.