microsoft / microsoft/TypeScript

Typecheck code blocks in jsdoc

Ouverte
#62,383 0 commentaires 1 réaction 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

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

jsdoc typecheck

### ✅ 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 a codeblock is created in jsdoc, apply typechecking on it as if it were part of the code in the file.

### 📃 Motivating Example

I create a method that has a non-trivial function signature (example is contrived)
```ts
type OtherType = { data: TData };
class Class {
doSomething(arg: OtherType): void;
}
```
I would like to document the idiomatic usage in jsdoc
```ts
/**
* Does something, example:
* ```ts
* const cls = new Class<{ x: number }>();
* cls.doSomething({ data: { x: 1, y: 2 } });
* ```
*/
```
If the function signature or underlying types change in any way, the typechecker will tell me to update the usages, but not the example.
The example becomes outdated potentially unknowingly, potentially causing bad code that could have been prevented if the example was typechecked.

### 💻 Use Cases

1. What do you want to use this for?

Typecheck code blocks in jsdoc

2. What shortcomings exist with current approaches?

Relying on implementations as the idiomatic way when the example in the jsdoc is intended the be the idiomatic way.

3. What workarounds are you using in the meantime?

Inspection

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Aucun fichier, test ou point d’entrée n’est nommé. La recherche doit identifier les blocs de code JSDoc et les points d’entrée du contrôle de types, puis définir des tests montrant que les exemples sont vérifiés par rapport aux déclarations environnantes sans modifier le JavaScript généré.

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

Évaluation

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

Recevez les nouvelles issues par e-mail

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