microsoft / microsoft/TypeScript

JSDoc `@` in the code block is broken

Ouverte
#61,640 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Domain: JSDoc Help Wanted Possible Improvement
Langage dominant
Go
Étoiles
111k
Forks
14.3k
Merge moyen
2 j 4 h
PR mergées (30 j)
132

Description

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

```

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par reproduire les trois exemples JSDoc dans VS Code 1.97.2, en vous concentrant sur les at-rules CSS @media à l’intérieur des blocs de code Markdown et des balises @example. Aucun fichier source ni aucun test n’est nommé ; le travail est considéré comme terminé lorsque les exemples sont rendus sans traiter @media comme une balise JSDoc ni casser le bloc de code.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
css, markdown, typescript
Domaine
documentation, tooling
Type d'issue
Bug
Difficulté
4/5
Temps estimé
3-5 jours
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.