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

🔍 Search Terms

fileoverview

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• 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 tag to document a file (module). Synonyms are @fileoverview and @overview.

Currently TypeScript allows you to document a module like this:

/**
 * 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:

/**
 * 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.

/**
 * @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 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.

首先跟踪现有模块描述的收集方式以及它们如何显示在 hover 中，然后检查 JSDoc 处理和 autocomplete 路径。确定 @file、@fileoverview 和 @overview 标签应如何在没有 declare module 的情况下识别模块。当模块描述对所示的导出模式生效，并且在 hover 和 autocomplete 中一致显示时，即表示完成。