Rethink description comment format in CSS syntax boxes

### MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow

### What specific section or headline is this issue about?

Syntax

### What information was incorrect, unhelpful, or incomplete?

```css
/* Keyword values */
box-shadow: none;

/* A color and two length values */
/* | | */
box-shadow: red 60px -16px;

/* Three length values and a color */
/* | | | */
box-shadow: 10px 5px 5px black;

/* Four length values and a color */
/* | | | | */
box-shadow: 2px 2px 2px 1px rgb(0 0 0 / 20%);

/* inset, length values, and a color */
/* | | | */
box-shadow: inset 5em 1em gold;

/* Any number of shadows, separated by commas */
box-shadow:
3px 3px red inset,
-1em 0 0.4em olive;
```

### What did you expect to see?

```css
/* Keyword values */
box-shadow: none;

/* offset-x | offset-y | color */
box-shadow: 60px -16px teal;

/* offset-x | offset-y | blur-radius | color */
box-shadow: 10px 5px 5px black;

/* offset-x | offset-y | blur-radius | spread-radius | color */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);

/* inset | offset-x | offset-y | color */
box-shadow: inset 5em 1em gold;

/* Any number of shadows, separated by commas */
box-shadow:
3px 3px red,
-1em 0 0.4em olive;
```

### Do you have any supporting links, references, or citations?

I am trying to learn HTML & CSS and I noticed that the syntax examples for `box-shadow` were updated around 2023 in this [PR](https://github.com/mdn/content/pull/29013) to use generic descriptors like `` and ``, instead of the earlier more explicit syntax annotations such as:

```
/* offset-x | offset-y | blur-radius | spread-radius | color */
```

What used to be:

```
/* offset-x | offset-y | blur-radius | color */
box-shadow: 10px 5px 5px black;

/* offset-x | offset-y | blur-radius | spread-radius | color */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);
```

Became:

```
/* Three length values and a color */
/* | | | */
box-shadow: 10px 5px 5px black;

/* Four length values and a color */
/* | | | | */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);
```

As a learner, I found the older format much clearer and easier to reference. I only found about it as the video where I was learning it from showed the older content.

Would it be possible to restore the explicit syntax in comments OR at least explain to me why the newer content is better?

### Do you have anything more you want to share?

_No response_

### MDN metadata

Page report details

* Folder: `en-us/web/css/box-shadow`
* MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow
* GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/box-shadow/index.md
* Last commit: https://github.com/mdn/content/commit/0cc9980e3b21c83d1800a428bc402ae1865326b2
* Document last modified: 2025-07-14T14:43:58.000Z