microsoft / microsoft/TypeScript

Add support for `@file` jsdoc tag to describe a module

Ouverte
#63,695 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

`fileoverview`

### ✅ 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

JSDoc supports the [`@file`](https://jsdoc.app/tags-file) tag to document a file (module). Synonyms are `@fileoverview` and `@overview`.

Currently TypeScript allows you to document a module like this:

```ts
/**
* This comment describes `some-module`.
*/
declare module 'some-module' {
/**
* This comment describes `fn`.
*/
export function fn(): unknown;
}
```

This description shows up when you hover over an import of `some-module`.

However, it’s generally considered more idiomatic avoid `declare module`:

```ts
/**
* This comment describes `fn`.
*/
export function fn(): unknown;
```

In this case, there’s not way to describe the module.

I believe the `@file` tag provides a perfect way to describe a module. So the following code would be equivalent to the original example above.

```ts
/**
* @file
* This comment describes `some-module`.
*/

/**
* This comment describes `fn`.
*/
export function fn(): unknown;
```

I noticed that current module descriptions show up on hover, but not in autocomplete. I believe it would be nice to add support for that too.

### 📃 Motivating Example

TypeScript now supports the [`@file`](https://jsdoc.app/tags-file) tag to describe a module.

### 💻 Use Cases

1. What do you want to use this for?

I would describe modules. It would be nice to generate documentation from source as well.

2. What shortcomings exist with current approaches?

It can’t be done without `declare module`.

3. What workarounds are you using in the meantime?

I don’t document modules.

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

Commencez par retracer la manière dont les descriptions de modules existantes sont collectées et affichées dans hover, puis examinez le traitement de JSDoc et les chemins d’autocomplete. Déterminez comment les balises @file, @fileoverview et @overview doivent identifier un module sans declare module. Le travail est terminé lorsque les descriptions de modules fonctionnent pour le modèle d’exportation présenté et apparaissent de manière cohérente dans hover et autocomplete.

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

Évaluation

Stack technique
javascript, typescript
Domaine
developer-experience, documentation
Type d'issue
Fonctionnalité
Difficulté
4/5
Temps estimé
3-5 jours
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
52/100

Recevez les nouvelles issues par e-mail

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