microsoft / microsoft/TypeScript
Omit JSDoc type directives when emitting type declarations with documentation
まだ誰も着手していません。
- 主要言語
- Go
- スター
- 111k
- フォーク
- 14.3k
- 平均マージ
- 2日 4時間
- マージ済み PR(30日)
- 132
説明
### 🔍 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.
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
css-select-adapter.js と示されている tsconfig.json を使って宣言のみの出力を再現し、JSDoc が生成された宣言にどのように引き継がれるかを追跡する。@type、@typedef、@template、@param、@returns に対してサポートする stripping の動作を定義し、空のドキュメントを削除する場合も含める。done には、提案された出力とそのエッジケースのカバレッジを含めること。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- javascript, typescript
- 領域
- compilers
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 35/100