Define definition conventions

index.bs

@@ -1872,11 +1872,19 @@ it declares a [=static attribute=]. Note that in addition to being [=interface m
 
 <div algorithm>
     To <dfn export>get the underlying value</dfn> of an attribute |attr| given a value |target|,
-    return the result of performing the actions listed in the description of |attr| that occur on getting,
+    return the result of performing the actions listed in the getter description of |attr|,
     or those listed in the description of the inherited attribute,
     if |attr| is declared to inherit its getter, with |target| as <b>[=this=]</b> if it is not null.
 </div>
 
+The getter description of an attribute _attr_, should be of the form “The
+<code><var>attr</var></code> getter steps are:” followed by a list or “The
+<code><var>attr</var></code> getter steps are to” followed by an inline description.
+
+The setter description of an attribute _attr_, should be of the form “The
+<code><var>attr</var></code> setter steps are:” followed by a list or “The
+<code><var>attr</var></code> setter steps are to” followed by an inline description.
+
 The [=identifier=] of an
 [=attribute=]
 must not be the same as the identifier
@@ -2422,6 +2430,10 @@ The following extended attributes are applicable to operations:
 [{{SecureContext}}],
 [{{LegacyUnforgeable}}].
 
+The method description of an operation _operation_, should be of the form “The method
+<code><var>operation</var></code> steps are:” followed by a list or “The
+<code><var>operation</var></code> steps are to” followed by an inline description.
+
 <pre class="grammar" id="prod-DefaultValue">
     DefaultValue :
         ConstValue
@@ -2589,10 +2601,9 @@ in which case the [=default toJSON operation=] is exposed instead.
 
     <div algorithm="example tojson">
 
-        To invoke the <code>toJSON()</code> operation of the <code class="idl">Transaction</code>
-        interface, run the following steps:
+        The <code>toJSON()</code> method steps are:
 
-        1.  Let |json| be a new <code class="idl">TransactionJSON</code> dictionary.
+        1.  Let |json| be a new [=map=].
         1.  [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »:
             1.  Let |value| be result of [=get the underlying value|getting the underlying value=]
                 of the [=attribute=] identified by |attr|,
@@ -2634,8 +2645,16 @@ Multiple [=constructor operations=] may appear on a given [=interface=].
 For each [=constructor operation=] on the [=interface=], there will be a way to attempt to
 construct an instance by passing the specified arguments.
 
-The prose definition of a [=constructor operation=] must either initialize the value passed as
-<b>[=this=]</b>, or throw an exception.
+The constructor description of a [=constructor operation=] must either initialize the value passed
+as <b>[=this=]</b>, or throw an exception.
+
+The constructor description of a constructor _constructor_, should be of the form “The
+<code>new <var>constructor</var></code> constructor steps are:” followed by a list or “The
+<code>new <var>constructor</var></code> constructor steps are to” followed by an inline description.
+
+<p class=example id=example-constructor-description>If the constructor does not initialize
+<b>[=this=]</b>, one can write “The <code>new Example(<var ignore>init</var>)</code> constructor
+steps are to do nothing.”
 
 See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented.
 
@@ -2771,7 +2790,7 @@ will not be such functionality.
 Defining a special operation  with an [=identifier=]
 is equivalent to separating the special operation out into its own
 declaration without an identifier.  This approach is allowed to
-simplify prose descriptions of an interface’s operations.
+simplify method descriptions of an interface’s operations.
 
 <div class="example">
 
@@ -2965,22 +2984,17 @@ a [=static attribute=].
         };
     </pre>
 
-    Thus, prose is required to explain the stringification behavior, such
-    as the following paragraph:
+    Thus, prose is required to explain the stringification behavior.
+    We assume that the <code class="idl">familyName</code> and
+    <code class="idl">givenName</code> attributes are backed by
+    family name and given name concepts, respectively.
 
     <blockquote>
 
-        Objects that implement the <code class="idl">Student</code>
-        interface must stringify as follows.  If the value of the
-        <code class="idl">familyName</code> attribute is
-        <emu-val>null</emu-val>, the stringification of the
-        object is the value of the <code class="idl">givenName</code>
-        attribute.  Otherwise, if the value of the
-        <code class="idl">familyName</code> attribute is not <emu-val>null</emu-val>,
-        the stringification of the object is the concatenation of the
-        value of the <code class="idl">givenName</code> attribute,
-        a single space character, and the value of
-        the <code class="idl">familyName</code> attribute.
+        The stringification behavior steps are:
+
+        1. If [=this=]'s family name is null, then return [=this=]'s given name.
+        2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name.
 
     </blockquote>
 
@@ -3992,25 +4006,24 @@ determine what Web IDL language feature to use:
     Even though the IDL is shorter in the second version, two distinctively different concepts are
     conflated in the first argument. Without [=overloaded|overloads=], the question "is <var
     ignore>property</var> or <var ignore>conditionText</var> paired with <var ignore>value</var>?"
-    is much more difficult to answer without reading the prose definition of the operation. This
+    is much more difficult to answer without reading the method description of the operation. This
     makes the second version remarkably less readable than the first.
 
-    Another consideration is that the prose for [=overloaded=] operations can be specified in
-    separate blocks, which can aid in both reading and writing specifications. This is not the case
-    for [=optional arguments=]. This means that in the first case the specification author can write
-    the prose definition of the operations as:
+    Another consideration is that the method description for [=overloaded=] operations can be
+    specified in separate blocks, which can aid in both reading and writing specifications. This is
+    not the case for [=optional arguments=]. This means that in the first case the specification
+    author can write the method descriptions of the operations as:
 
     <div algorithm="execute supports() with overloads">
 
         The <code class="idl">supports(<var ignore>property</var>, <var ignore>value</var>)</code>
-        method, when called, must run these steps:
+        method steps are:
 
         1.  …
 
         ----
 
-        The <code class="idl">supports(<var ignore>conditionText</var>)</code> method, when called,
-        must run these steps:
+        The <code class="idl">supports(<var ignore>conditionText</var>)</code> method steps are:
 
         1.  …
 
@@ -4021,8 +4034,7 @@ determine what Web IDL language feature to use:
 
     <div algorithm="execute supports() with optional argument">
 
-        The <code class="idl">supports(|propertyOrConditionText|, |value|)</code> method, when
-        called, must run these steps:
+        The <code class="idl">supports(|propertyOrConditionText|, |value|)</code> method steps are:
 
         1.  If |value| is given, then:
             1.  Let <var ignore>property</var> be |propertyOrConditionText|.
@@ -14465,8 +14477,9 @@ requirements beyond the normal ones for [=interface types=].
 Each {{DOMException}} object has an associated <dfn for="DOMException">name</dfn> and
 <dfn for="DOMException">message</dfn>, both [=strings=].
 
-The <dfn constructor for="DOMException"><code>DOMException(|message|, |name|)</code></dfn>
-constructor, when invoked, must run these steps:
+The
+<dfn constructor for="DOMException" lt="DOMException(message, name)"><code>new DOMException(|message|, |name|)</code></dfn>
+constructor steps are:
 
 1. Set <b>this</b>'s [=DOMException/name=] to |name|.
 1. Set <b>this</b>'s [=DOMException/message=] to |message|.