microsoft / microsoft/TypeScript

JSDoc `@` in the code block is broken

未关闭
#61,640 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

Domain: JSDoc Help Wanted Possible Improvement
主要语言
Go
星标
111k
派生
14.3k
平均合并
2 天 4 小时
30 天内合并 PR
132

描述

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

```

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先在 VS Code 1.97.2 中复现这三个 JSDoc 示例,重点关注 Markdown 代码块和 @example 标签中的 CSS @media at-rule。未指定源文件或测试;当示例能够正常渲染,且不会将 @media 当作 JSDoc 标签或破坏代码块时,即视为完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
css, markdown, typescript
领域
documentation, tooling
Issue 类型
缺陷
难度
4/5
预计耗时
3-5 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。