[css-pseudo-4] Clarify return value of element.pseudo() - identity is stable per element/type pair, returns null for unknown types. #3607 #3603

Author: fantasai

css-pseudo-4/Overview.bs

@@ -834,7 +834,7 @@ Overlapping Pseudo-element Interactions</h2>
 Additions to the CSS Object Model</h2>
 
 <h3 id="CSSPseudoElement-interface">
-Interface CSSPseudoElement</h3>
+{{CSSPseudoElement}} Interface</h3>
 
   The {{CSSPseudoElement}} interface
   allows pseudo-elements to be event targets.
@@ -871,7 +871,7 @@ Interface CSSPseudoElement</h3>
   to that which is needed to support [[web-animations-1]].
 
 <h3 id="window-interface">
-Addition to the {{Element}} interface</h3>
+{{pseudo()}} method of the {{Element}} interface</h3>
 
   A new method is added to the {{Element}} interface to retrieve
   pseudo-elements created by a given element for a given type:
@@ -883,12 +883,14 @@ Addition to the {{Element}} interface</h3>
 
   The <dfn method for=Element title="pseudo(type)" id="dom-element-pseudo">pseudo(CSSOMString type)</dfn> method
   is used to retrieve the {{CSSPseudoElement}} instance
-  created by the element of the type matching {{type!!argument}}.
-  Its return value is a {{CSSPseudoElement}},
-  potentially null if no such pseudo-element exists.
-
-  Pseudo-elements of unsupported types are considered to simply not exist;
-  unrecognized {{type!!argument}} values are not an error.
+  of the type matching {{type!!argument}}
+  associated with the element.
+  Its return value on a given element
+  for a given, supported {{CSSPseudoElement}} {{CSSPseudoElement/type}} is,
+  insofar as observable, always the same {{CSSPseudoElement}} object.
+  (The UA may drop or regenerate the object for convenience or performance
+  if this is not observable.)
+  For unrecognized types, the return value is null.
 
   ISSUE: The identity, lifetime, and nullness of the return value
   (and potential error cases)
@@ -911,6 +913,7 @@ Changes</h2>
 
   <ul>
     <li>Added ''::marker'' to types allowed for {{CSSPseudoElement}} interface.
+    <li>Clarified return value of {{pseudo()}}.
   </ul>
 
   Changes since the <a href="https://www.w3.org/TR/2016/WD-css-pseudo-4-20160607/">7 June 2016 Working Draft</a> include: