Re: [heycam/webidl] Define definition conventions (#882)

@TimothyGu commented on this pull request.



> +The <dfn>getter steps</dfn> of an attribute |attr| should be introduced using text of the form “The
+<code>|attr|</code> getter steps are:” followed by a list, or “The <code>|attr|</code> getter steps

I believe we use straight quotes in this document…

> @@ -2634,8 +2637,17 @@ 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 [=this=], or throw an exception.
+
+The <dfn>constructor steps</dfn> of a constructor _constructor_ should be introduced using text of

`_constructor_` should be `|constructor|`, no? Also do we want to say `[=constructor operation=] |constructor|`? It seems moderately important to distinguish between constructor operations and constructors since the latter link to [JavaScript's definition](https://tc39.github.io/ecma262/#constructor) in the document.

> +<p class=example id=example-constructor-description>If the constructor does not initialize
+[=this=], one can write “The <code>new Example(<var ignore>init</var>)</code> constructor
+steps are to do nothing.”

Isn't this contradictory to the above

> The constructor description of a constructor operation must either initialize the value passed
as this, or throw an exception.

> @@ -2634,8 +2637,17 @@ 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

What does the "constructor description of a constructor operation" mean? Can we say "the constructor steps of each constructor operation"?

Also applies to "method description", etc.

>  
     <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:

How about just

```suggestion
        The [=stringification behavior=] is:
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/heycam/webidl/pull/882#pullrequestreview-411042958