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

@domenic commented on this pull request.

I'm a bit unsure about introducing the separate concept of "getter description" vs. "getter steps". Maybe instead a phrasing like

> The getter steps of an attribute _attr_ should be introduced using text of the form "The ...", or text of the form "The ..." followed by an inline description.

>      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

```suggestion
The getter description of an attribute _attr_ should be of the form “The
```

> @@ -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|,

Maybe "the result of performing the |attr| getter steps"?

>      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

```suggestion
The setter description of an attribute _attr_ should be of the form “The
```

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

```suggestion
The method description of an operation _operation_ should be of the form “The method
```

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

```suggestion
The constructor description of a constructor _constructor_ should be of the form “The
```

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