docs(css): Add description fields to CSS data schema files

css/at-rules.md

@@ -65,7 +65,7 @@ The `descriptors` object (when included) contains one or more objects that descr
 
 Each `descriptors` object consists of 7 required properties:
 * `syntax` (string): The syntax / possible values of the descriptor.
-* `media` (string): The media groups the descriptor applies to, e.g. "all, visual" (multiple values are comma-separated).
+* `media` (string): The media groups the descriptor applies to, e.g. "all", "visual" (multiple values are stored in an array).
 * `percentages` (string or array of strings):
   * If it is an array, the elements are the other descriptors this descriptor is taking the percentages from (array elements must be in a descriptors list).
   * If it is a string, it indicates the percentage value of the descriptor.

css/at-rules.schema.json

@@ -26,6 +26,7 @@
     "additionalProperties": false,
     "properties": {
       "syntax": {
+        "description": "This is the formal syntax of the at-rule and is usually found in the specification.",
         "type": "string"
       },
       "interfaces": {
@@ -35,6 +36,7 @@
         }
       },
       "groups": {
+        "description": "CSS is organized in modules like \"CSS Fonts\" or \"CSS Animations\".\nMDN organizes features in these groups as well — `groups` should contain the name of the module(s) the at-rule is defined in.",
         "type": "array",
         "minitems": 1,
         "uniqueItems": true,
@@ -43,15 +45,18 @@
         }
       },
       "descriptors": {
+        "description": "The `descriptors` object (when included) contains one or more objects that describe the different descriptors available on the at-rule.",
         "type": "object",
         "additionalProperties": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
             "syntax": {
+              "description": "This is the formal syntax of the at-rule and is usually found in the specification.",
               "type": "string"
             },
             "media": {
+              "description": "The media groups the descriptor applies to, e.g. \"all, visual\" (multiple values are comma-separated).",
               "oneOf": [
                 {
                   "type": "string",
@@ -93,6 +98,7 @@
               ]
             },
             "status": {
+              "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
               "enum": [
                 "standard",
                 "nonstandard",
@@ -112,13 +118,15 @@
         }
       },
       "status": {
+        "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
         "enum": [
           "standard",
           "nonstandard",
           "experimental"
         ]
       },
       "mdn_url": {
+        "description": "URL linking to the at-rule's page on MDN.\bThis URL must omit the localization part of the URL (such as `en-US/`).",
         "type": "string",
         "pattern": "^https://developer.mozilla.org/docs/Web/CSS/"
       }

css/properties.md

@@ -94,7 +94,7 @@ There are 11 required properties in this object:
 For more information see also
 [Value definition syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax)
 on MDN and the [CSS Values and Units](https://www.w3.org/TR/css3-values/#value-defs) specification.
-* `media` (string): The media groups this property applies to, e.g. "all, visual" (multiple values are comma-separated).
+* `media` (string): The media groups this property applies to, e.g. "all", "visual" (multiple values are stored in an array).
 * `inherited` (boolean): Whether or not the property is inherited. See [inheritance](https://developer.mozilla.org/en-US/docs/Web/CSS/inheritance) for details.
 * `animationType` (enum or array of property names):
   * If it is an enum (appropriate for long-hand properties), this is the animation type of the property.

css/properties.schema.json

@@ -152,7 +152,7 @@
         "twoAbsoluteLengths"
       ]
     },
-    "appliesto": {
+    "appliesTo": {
       "enum": [
         "absolutelyPositionedElements",
         "allElements",
@@ -287,9 +287,11 @@
     ],
     "properties": {
       "syntax": {
+        "description": "This is the formal syntax of the property and is usually found in the specification. It might contain references to syntax data.",
         "type": "string"
       },
       "media": {
+        "description": "The media groups this property applies to, e.g. \"all\", \"visual\" (multiple values are stored in an array).",
         "oneOf": [
           {
             "type": "string",
@@ -321,29 +323,35 @@
         ]
       },
       "inherited": {
+        "description": "Whether or not the property is inherited.",
         "type": "boolean"
       },
       "animationType": {
         "oneOf": [
           {
+            "description": "If it is an enum (appropriate for long-hand properties), this is the animation type of the property.",
             "$ref": "#/definitions/animationType"
           },
           {
+            "description": "If it is an array (appropriate for short-hand properties), these are the properties the animation type is taken from.",
             "$ref": "#/definitions/propertyList"
           }
         ]
       },
       "percentages": {
         "oneOf": [
           {
+            "description": "If it is an enum (appropriate for long-hand properties), this defines what the percentage actually refers to when a percentage is set as a value on the property (\"no\" means that the property can't accept a percentage as a value).",
             "$ref": "#/definitions/percentages"
           },
           {
+            "description": "If it is an array (appropriate for short-hand properties), these are the long-hand properties making up part of the short-hand value that percentages can be set as values for.",
             "$ref": "#/definitions/propertyList"
           }
         ]
       },
       "groups": {
+        "description": "CSS is organized in modules like \"CSS Fonts\" or \"CSS Animations\".\nMDN organizes features in these groups as well — `groups` should contain the name of the module(s) the property is defined in.",
         "type": "array",
         "minitems": 1,
         "uniqueItems": true,
@@ -354,39 +362,49 @@
       "initial": {
         "oneOf": [
           {
+            "description": "If it is a string (appropriate for long-hand properties), this is the initial value of the property.",
             "type": "string"
           },
           {
+            "description": "If it is an array (appropriate for short-hand properties), these are the properties the initial value is taken from.",
             "$ref": "#/definitions/propertyList"
           }
         ]
       },
       "appliesto": {
-        "$ref": "#/definitions/appliesto"
+        "description": "To which elements the property can be applied to.",
+        "$ref": "#/definitions/appliesTo"
       },
       "alsoAppliesTo": {
+        "description": "To which elements the property also applies to.",
         "$ref": "#/definitions/alsoApplyTo"
       },
       "computed": {
         "oneOf": [
           {
+            "description": "If it is an enum (appropriate for long-hand properties), this is the computed value of the property.",
             "$ref": "#/definitions/computed"
           },
           {
+            "description": "If it is an array (appropriate for short-hand properties), these are the properties the value is computed from.",
             "$ref": "#/definitions/propertyList"
           }
         ]
       },
       "order": {
+        "description": "The canonical order for the property.",
         "$ref": "#/definitions/order"
       },
       "stacking": {
+        "description": "Whether or not the property creates a stacking context.",
         "type": "boolean"
       },
       "status": {
+        "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
         "$ref": "#/definitions/status"
       },
       "mdn_url": {
+        "description": "URL linking to the property's page on MDN.\nThis URL must omit the localization part of the URL (such as `en-US/`).",
         "$ref": "#/definitions/mdn_url"
       }
     }

css/selectors.schema.json

@@ -5,9 +5,11 @@
     "additionalProperties": false,
     "properties": {
       "syntax": {
+        "description": "The syntax of the selector.",
         "type": "string"
       },
       "groups": {
+        "description": "CSS is organized in modules like \"CSS Units\" or \"CSS Lengths\".\nMDN organizes features in these groups as well — `groups` should contain the name of the module(s) the selector is defined in.",
         "type": "array",
         "minitems": 1,
         "uniqueItems": true,
@@ -16,13 +18,15 @@
         }
       },
       "status": {
+        "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
         "enum": [
           "standard",
           "nonstandard",
           "experimental"
         ]
       },
       "mdn_url": {
+        "description": "URL linking to the selector's page on MDN.\nThis URL must omit the localization part of the URL (such as `en-US/`).",
         "type": "string",
         "pattern": "^https://developer.mozilla.org/docs/Web/CSS/"
       }

css/syntaxes.md

@@ -40,7 +40,7 @@ Or, syntaxes might reference other syntaxes that are also defined in syntaxes.js
   "syntax": "<length> | <percentage>"
 },
 "shape-radius": {
-    "syntax": "<length-percentage> | closest-side | farthest-side"
+  "syntax": "<length-percentage> | closest-side | farthest-side"
 },
 ```
 

css/types.schema.json

@@ -5,6 +5,7 @@
     "additionalProperties": false,
     "properties": {
       "groups": {
+        "description": "CSS is organized in modules like \"CSS Types\" or \"CSS Color\".\nMDN organizes features in these groups as well — `groups` should contain the name of the module(s) the type is defined in.",
         "type": "array",
         "minitems": 1,
         "uniqueItems": true,
@@ -13,13 +14,15 @@
         }
       },
       "status": {
+        "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
         "enum": [
           "standard",
           "nonstandard",
           "experimental"
         ]
       },
       "mdn_url": {
+        "description": "URL linking to the type's page on MDN.\nThis URL must omit the localization part of the URL (such as `en-US/`).",
         "type": "string",
         "pattern": "^https://developer.mozilla.org/docs/Web/CSS/"
       }

css/units.schema.json

@@ -5,6 +5,7 @@
     "additionalProperties": false,
     "properties": {
       "groups": {
+        "description": "CSS is organized in modules like \"CSS Units\" or \"CSS Lengths\".\nMDN organizes features in these groups as well — `groups` should contain the name of the module(s) the unit is defined in.",
         "type": "array",
         "minitems": 1,
         "uniqueItems": true,
@@ -13,6 +14,7 @@
         }
       },
       "status": {
+        "description": "This is either `standard`, `nonstandard`, or `experimental` depending on the standardization status of the feature.",
         "enum": [
           "standard",
           "nonstandard",