[css-mixins-1] Review by elika

Author: tabatkins

css-mixins-1/Overview.bs

@@ -116,7 +116,7 @@ Introduction {#intro}
 
 	.foo {
 		--shadow-color: blue;
-		box-shadow: --shadow(); // produces a blue shadow
+		box-shadow: --shadow(); /* produces a blue shadow */
 		/* or just */
 		box-shadow: --shadow(blue);
 	}
@@ -184,7 +184,7 @@ a list of [=function parameter|parameters=],
 a <dfn for="custom function">function body</dfn>,
 and optionally a <dfn for="custom function">return type</dfn> described by a [=syntax definition=].
 
-A <dfn>function parameter</dfn> consists of a name (<<custom-property-name>>);
+Each <dfn>function parameter</dfn> consists of a name (<<custom-property-name>>);
 optionally a <dfn>parameter type</dfn>, described by a [=syntax definition=];
 and optionally a <dfn>default value</dfn>.
 
@@ -200,6 +200,9 @@ and optionally a <dfn>default value</dfn>.
 <dfn function lt="type()" for="@function">&lt;type()></dfn> = type( <<syntax>> )
 </pre>
 
+<h4 id=function-preamble>
+The Function Preamble</h4>
+
 The <<function-token>> production
 must start with two dashes (U+002D HYPHEN-MINUS),
 similar to <<dashed-ident>>,
@@ -233,22 +236,27 @@ and the optional [=custom function/return type=] is given by the <<css-type>> fo
 </div>
 
 
+The name of a ''@function'' rule is a [=tree-scoped name=].
 If more than one ''@function'' exists for a given name,
 then the rule in the stronger cascade layer wins,
 and rules defined later win within the same layer.
 
-The name of a ''@function'' rule is a [=tree-scoped name=].
-
 If the <<function-parameter-list>>
 contains the same <<custom-property-name>> more than once,
 then the ''@function'' rule is invalid.
 
+<h4 id=function-body>
+The Function Body</h4>
+
 The body of a ''@function'' rule accepts [=conditional group rules=],
 such as ''@media''.
 Additionally, it accepts the following descriptors:
 
 	* The '@function/result' descriptor,
 		which determines the result of [=evaluating a custom function|evaluating the function=].
+		If no '@function/result' descriptor exists,
+		the function is valid,
+		but always returns the [=guaranteed-invalid value=].
 	* [=Custom properties=],
 		providing <dfn>local variables</dfn>.
 
@@ -266,14 +274,14 @@ Initial: n/a (see prose)
 </pre>
 
 The '@function/result' descriptor
-determines the result of [=evaluate a custom function|evaluating=]
-the [=custom function=] that is defined by a ''@function'' rule.
+defines the result of [=evaluate a custom function|evaluating=]
+the [=custom function=] defined by its ''@function'' rule.
 Using ''var()'' functions,
 it can reference [=function parameters=], [=local variables=],
 as well as other [=custom functions=] via <<dashed-function>>s.
 
 The '@function/result' descriptor itself does not have a type,
-but its [=resolve function styles|resolved=] value is type checked
+but its [=resolve function styles|resolved=] value is type-checked
 during the [=substitute a dashed function|substitution=] of a <<dashed-function>>.
 
 Arguments & Local Variables {#args}
@@ -294,11 +302,11 @@ In that list, earlier things "win" over later things of the same name--
 if you have a [=local variable=] named '--foo',
 ''var(--foo)'' will be substituted by that [=local variable=],
 not by an argument or a custom property defined outside.
-(The other values can still be <em>accessed</em>, however:
+The other values can still be <em>accessed</em>, however:
 setting the '--foo' local variable to ''initial''
 will resolve it to the '--foo' parameter,
 while ''inherit'' will resolve it
-to the '--foo' custom property from the call site.)
+to the '--foo' custom property from the call site.
 
 <div class='example'>
 	A [=custom function=] can access [=local variables=]