microsoft / microsoft/TypeScript

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

Open
#63,695 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Awaiting More Feedback Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing how existing module descriptions are collected and surfaced in hover, then inspect the JSDoc processing and autocomplete paths. Determine how the @file, @fileoverview, and @overview tags should identify a module without declare module. Done means module descriptions work for the shown export pattern and appear consistently in hover and autocomplete.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
developer-experience, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.