microsoft / microsoft/TypeScript

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

Đang mở
#63,695 0 bình luận 1 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Awaiting More Feedback Suggestion
Ngôn ngữ chính
Go
Star
111k
Fork
14.3k
Merge trung bình
2 ngày 4 giờ
Pull request đã merge (30 ngày)
132

Mô tả

### 🔍 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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu bằng cách lần theo cách các mô tả module hiện có được thu thập và hiển thị trong hover, sau đó kiểm tra quá trình xử lý JSDoc và các đường dẫn autocomplete. Xác định cách các tag @file, @fileoverview và @overview cần nhận diện một module mà không có declare module. Được xem là hoàn tất khi các mô tả module hoạt động với mẫu export được hiển thị và xuất hiện nhất quán trong hover và autocomplete.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript, typescript
Lĩnh vực
developer-experience, documentation
Loại issue
Tính năng
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
52/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.