microsoft / microsoft/TypeScript
Omit JSDoc type directives when emitting type declarations with documentation
- 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
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