Embellish discouraged data with more detail

Author: ddbeck

features/accessor-methods.yml

@@ -2,6 +2,7 @@ name: Accessor methods
 description: The `__defineGetter__()` and `__defineSetter__()` methods of objects bind a function to a property, which is called on setting or reading the property.
 spec: https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.prototype-legacy-accessor-methods
 discouraged:
+  reason: TC39 included accessor methods in Annex B of the ECMAScript specification, which covers JavaScript features with "one or more undesirable characteristics and in the absence of legacy usage would be removed."
   according_to:
     - https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers
     # No `alternatives` because it would be `alternatives:

features/arguments-callee.yml

@@ -6,6 +6,7 @@ discouraged:
   # From note 4: "The definition of this property […] exists to ensure that it
   # is not defined in any other manner by conforming ECMAScript
   # implementations."
+  reason: JavaScript strict mode prohibits accessing `arguments.callee`.
   according_to:
     - https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-arguments-exotic-objects
 compat_features:

features/clip.yml

@@ -3,6 +3,7 @@ description: The `clip` CSS property sets the visible area of an absolutely posi
 spec: https://drafts.fxtf.org/css-masking-1/#clip-property
 group: clipping-shapes-masking
 discouraged:
+  reason: The CSS Masking specification deprecated the `clip` property.
   according_to:
     - https://drafts.fxtf.org/css-masking-1/#clip-property
   alternatives:

features/color-adjust.yml

@@ -3,6 +3,7 @@ description: The `color-adjust` shorthand CSS property allows multiple performan
 spec: https://drafts.csswg.org/css-color-adjust-1/#color-adjust
 group: print
 discouraged:
+  reason: The CSS Color Adjustment specification described the `color-adjust` as deprecated, to prevent authors from accidentally resetting color adjustments in unexpected contexts.
   according_to:
     - https://drafts.csswg.org/css-color-adjust-1/#color-adjust
   alternatives:

features/color-contrast.yml

@@ -3,6 +3,7 @@ description: "The `color-contrast()` CSS function picks a color from a list that
 spec: https://drafts.csswg.org/css-color-5/#contrast-color
 group: color-types
 discouraged:
+  reason: The CSS Color specification renamed `color-contrast()` to `contrast-color()`.
   # See these CSSWG discussions
   # https://github.com/w3c/csswg-drafts/issues/7557
   # https://github.com/w3c/csswg-drafts/issues/7359

features/css-object-model-discouraged.yml

@@ -3,6 +3,7 @@ description: The DOM level 2 style specification defined interfaces to access an
 spec: https://www.w3.org/TR/DOM-Level-2-Style/
 group: cssom
 discouraged:
+  reason: The DOM level 2 CSS object model was excluded from the later CSS object model (CSSOM) specification.
   according_to:
     - https://www.w3.org/TR/DOM-Level-2-Style/#Overview-status
   alternatives:

features/date-get-year-set-year.yml

@@ -3,6 +3,7 @@ description: The `getYear()` and `setYear()` methods of `Date` objects get and s
 spec: https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-date.prototype.getyear
 group: javascript
 discouraged:
+  reason: The `getYear()` and `setYear()` methods use a truncated number instead of the actual year number, known as a year 2000 problem.
   according_to:
     - https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers
   # No `alternatives` because it would be `alternatives: [date]`. In the future

features/mutation-events.yml

@@ -4,8 +4,11 @@ description: Mutation events like `DOMSubtreeModified`, `DOMNodeInserted`, or `D
 spec: https://w3c.github.io/uievents/
 group: dom
 discouraged:
+  pending_removal: true
+  reason: Mutation events negatively impact performance and they were selected for removal from the web as part of Interop 2025.
   according_to:
     - https://www.w3.org/TR/2024/WD-uievents-20240906/#legacy-mutationevent-events
+    - https://github.com/web-platform-tests/interop/issues/784
   alternatives:
     - mutationobserver
 compat_features: