Skip to content

JSDoc @ in the code block is broken #61640

Open
@otomad

Description

@otomad

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

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

Preview:

Image

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

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

Preview:

Image

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

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

Preview:

Image

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Help WantedYou can do thisPossible ImprovementThe current behavior isn't wrong, but it's possible to see that it might be better in some cases

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions