[css-mixins-1][editorial] Use a list for some conditions. Add some usage examples.

Author: tabatkins

css-mixins-1/Overview.bs

@@ -1202,15 +1202,17 @@ That is, it is either an <em>empty</em> statement ended immediately by a semicol
 or a block treated as a [=nested declarations rule=].
 The empty statement form behaves identically to passing an empty block.
 
-If the [=mixin=] did not declare a ''@contents'' parameter,
-the ''@contents'' rule is ignored,
-substituting with nothing.
-Otherwise, if the ''@apply'' rule invoking the [=mixin=] passed a [=contents block=],
-the ''@contents'' is replaced with the [=contents block=],
-treating it as a [=nested declarations rule=].
-Otherwise, if the ''@apply'' rule did not pass a [=contents block=],
-the ''@contents'' rule is replaced with its own <<declaration-list>>,
-treated as a [=nested declarations rule=].
+* If the [=mixin=] did not declare a ''@contents'' parameter,
+	the ''@contents'' rule is ignored,
+	substituting with nothing.
+	<span class=note>(And if the ''@apply'' rule tries to pass a [=contents blocks=],
+	it's an invalid invocation and has no effect.)</span>
+* Otherwise, if the ''@apply'' rule invoking the [=mixin=] passed a [=contents block=],
+	the ''@contents'' is replaced with the [=contents block=],
+	treating it as a [=nested declarations rule=].
+* Otherwise, if the ''@apply'' rule did not pass a [=contents block=],
+	the ''@contents'' rule is replaced with its own <<declaration-list>>,
+	treated as a [=nested declarations rule=].
 
 Outside of a [=mixin body=],
 the ''@contents'' rule is invalid and ignored.
@@ -1280,6 +1282,26 @@ Its grammar is:
 <<@apply>> = @apply [ <<dashed-ident>> | <<dashed-function>> ] [ { <<declaration-list>> } ]?;
 </pre>
 
+<div class=example>
+	For example, a [=mixin=] can be applied in any of these ways:
+
+	<pre highlight=css>
+	.foo {
+		@apply --one;
+		/* Invokes the --one mixin, with no arguments or contents. */
+
+		@apply --two(blue);
+		/* Invokes --two with one argument, and no contents. */
+
+		@apply --three {color: red;}
+		/* Invokes --three with no arguments, but with contents.
+
+		@apply --four(blue) {color: red;}
+		/* Invokes --four with both an argument and contents.
+	}
+	</pre>
+</div>
+
 The ''@apply'' rule is only valid
 in the body of a [=style rule=]
 or [=nested group rule=];
@@ -1313,6 +1335,40 @@ If the [=mixin=] did not declare a ''@contents'' parameter,
 having a <<declaration-list>> block makes the ''@apply'' rule invalid
 (similar to passing too many arguments).
 
+<div class=example>
+	Applying a mixin without arguments, or with an empty argument list,
+	is identical.
+	That is, these two invocations do exactly the same thing:
+
+	<pre highlight=css>
+	.foo {
+		@apply --no-args;
+	}
+	.bar {
+		@apply --no-args();
+	}
+	</pre>
+
+	Passing a [=contents block=] is <em>not</em> the same;
+	omitting the block entirely triggers fallback,
+	while passing an empty block will substitute the empty block:
+
+	<pre highlight=css>
+	@mixin --just-contents(@contents) {
+		@contents { content: "This is fallback." }
+	}
+
+	.foo {
+		@apply --just-contents;
+		/* substitutes with `content: "This is fallback.";` */
+	}
+	.bar {
+		@apply --just-contents {};
+		/* substitutes with nothing at all */
+	}
+	</pre>
+</div>
+
 
 <!-- Big Text: @env