microsoft / microsoft/TypeScript

JSDoc `@` in the code block is broken

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

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

Domain: JSDoc Help Wanted Possible Improvement
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ả

Type: Bug

When writing CSS example code in JSDoc, the `@` At-rules in CSS will break Markdown code blocks and incorrectly identify them as JSDoc tags.

### Examples

#### If the code block is not in the `@example` tag

````typescript
/**
* Does system use dark theme?
*
* ```css
* @media (prefers-color-scheme: dark) {
* color: white;
* }
* ```
*/
function isDarkTheme() { /* */ }
````

**Preview:**

![Image](https://github.com/user-attachments/assets/0a76dedf-71a8-415e-9917-636f3c3b5d0e)

As you can see, VSCode unexpectly added italic `* *` around the `@media` with a line break, but still in the code block.

#### If the code block is in the `@example` tag

````typescript
/**
* Does system use dark theme?
*
* @example
* ```css
* @media (prefers-color-scheme: dark) {
* color: white;
* }
* ```
*/
function isDarkTheme() { /* */ }
````

**Preview:**

![Image](https://github.com/user-attachments/assets/76722f2b-6d12-4355-99e4-7bc2df0f54b1)

As you can see, it will incorrectly identify `@media` CSS at-rule as JSDoc tag, and break the code block. Even displaying a pair of three grave accents (backticks) in the source code.

#### `@` at-rules is not at the beginning of the line

````typescript
/**
* Does system use dark theme?
*
* @example
* ```css
* other @media (prefers-color-scheme: dark) {
* color: white;
* }
* ```
*/
function isDarkTheme() { /* */ }
````

**Preview:**

![Image](https://github.com/user-attachments/assets/6c46eb1d-f7f2-4c91-a734-83ca723b4a0d)

Even if it's not at the beginning of the line, it still won't display correctly.

VS Code version: Code 1.97.2 (e54c774e0add60467559eb0d1e229c6452cf8447, 2025-02-12T23:20:35.343Z)
OS version: Windows_NT x64 10.0.26100
Modes:

System Info

|Item|Value|
|---|---|
|CPUs|12th Gen Intel(R) Core(TM) i5-12600KF (16 x 3686)|
|GPU Status|2d_canvas: enabled
canvas_oop_rasterization: enabled_on
direct_rendering_display_compositor: disabled_off_ok
gpu_compositing: enabled
multiple_raster_threads: enabled_on
opengl: enabled_on
rasterization: enabled
raw_draw: disabled_off_ok
skia_graphite: disabled_off
video_decode: enabled
video_encode: enabled
vulkan: disabled_off
webgl: enabled
webgl2: enabled
webgpu: enabled
webnn: disabled_off|
|Load (avg)|undefined|
|Memory (System)|31.82GB (18.18GB free)|
|Process Argv|--crash-reporter-id d8097863-1757-41d3-a8d8-c057a920ae69|
|Screen Reader|no|
|VM|0%|
Extensions disabled
A/B Experiments

```
vsliv368cf:30146710
vspor879:30202332
vspor708:30202333
vspor363:30204092
vscod805cf:30301675
binariesv615:30325510
py29gd2263:31024239
14424t2-chatv2:31241988
vscaac:30438847
c4g48928:30535728
azure-dev_surveyone:30548225
2i9eh265:30646982
962ge761:30959799
h48ei257:31000450
pythontbext0:30879054
cppperfnew:31000557
dwnewjupyter:31046869
nativerepl1:31139838
pythonrstrctxt:31112756
nativeloc1:31192215
iacca1:31171482
5fd0e150:31155592
dwcopilot:31170013
stablechunks:31184530
6074i472:31201624
dwoutputs:31242946
customenabled:31241370
5a9hg449:31230677
9064b325:31222308
copilot_t_ci:31222730
jda6j935:31233686
copilothoveron:31240708

```

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 tái hiện ba ví dụ JSDoc trong VS Code 1.97.2, tập trung vào các at-rule CSS @media bên trong các khối mã Markdown và các thẻ @example. Không có tệp nguồn hoặc bài kiểm thử nào được nêu; được coi là hoàn tất khi các ví dụ được kết xuất mà không coi @media là thẻ JSDoc hoặc làm hỏng khối mã.

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

Đánh giá

Công nghệ
css, markdown, typescript
Lĩnh vực
documentation, tooling
Loại issue
Lỗi
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/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.