microsoft / microsoft/TypeScript

Omit JSDoc type directives when emitting type declarations with documentation

Abierto
#61,664 0 comentarios 1 reacción 0 asignados Ver en GitHub
Awaiting More Feedback Suggestion
Lenguaje dominante
Go
Estrellas
111k
Forks
14.3k
Merge medio
2 d 4 h
PR fusionados (30 d)
132

Descripción

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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Reproduce la emisión solo de declaraciones usando css-select-adapter.js y el tsconfig.json mostrado; después, rastrea cómo se incorpora JSDoc a la declaración generada. Define el comportamiento de stripping admitido para @type, @typedef, @template, @param y @returns, incluido cuándo se elimina la documentación vacía; done debe incluir cobertura para la salida propuesta y sus casos límite.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
javascript, typescript
Área
compilers
Tipo de issue
Nueva funcionalidad
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
35/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.