microsoft / microsoft/TypeScript

Omit JSDoc type directives when emitting type declarations with documentation

Ouverte
#61,664 0 commentaires 1 réaction 0 personnes assignées Voir sur GitHub
Awaiting More Feedback Suggestion
Langage dominant
Go
Étoiles
111k
Forks
14.3k
Merge moyen
2 j 4 h
PR mergées (30 j)
132

Description

### 🔍 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.

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Reproduire l’émission des déclarations uniquement avec css-select-adapter.js et le tsconfig.json présenté, puis suivre la manière dont JSDoc est intégré à la déclaration générée. Définir le comportement de stripping pris en charge pour @type, @typedef, @template, @param et @returns, notamment dans quels cas la documentation vide est supprimée ; done doit inclure une couverture de la sortie proposée et de ses cas limites.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
javascript, typescript
Domaine
compilers
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.