Update API guidelines for the “form” prefix

api-design-guidelines/index.md

@@ -407,47 +407,64 @@ is printed.
   * Those with side-effects should read as imperative verb phrases,
     e.g., `print(x)`, `x.sort()`, `x.append(y)`.
 
-  * Use the “ed/ing” rule to name the nonmutating counterpart 
-    of a mutating method, e.g. `x.sort()`/`x.sorted()` and
-    `x.append(y)`/`x.appending(y)`.
+  * **Name Mutating/nonmutating method pairs** consistently.
+    A mutating method will often have a nonmutating variant with
+    similar semantics, but that returns a new value rather than
+    updating an instance in-place.
+
+    * When the operation is **naturally described by a verb**, use the
+      verb's imperative for the mutating method and apply the “ed” or
+      “ing” suffix to name its nonmutating counterpart.
+
+      |Mutating|Nonmutating|
+      |-
+      |`x.sort()`|`z = x.sorted()`|
+      |`x.append(y)`|`z = x.appending(y)`|
+
+      {{expand}}
+      {{detail}}
+
+      * Prefer to name the nonmutating variant using the verb's past
+        [participle](https://en.wikipedia.org/wiki/Participle) (usually
+        appending “ed”):
+
+        ~~~ swift
+        /// Reverses `self` in-place.
+        mutating func reverse()
+
+        /// Returns a reversed copy of `self`.
+        func revers**ed**() -> Self
+        ...
+        x.reverse()
+        let y = x.reversed()
+        ~~~
 
-    {{expand}}
-    {{detail}}
-    Often, a mutating method will have a nonmutating variant returning
-    the same, or a similar, type as the receiver.
+      * When adding “ed” is not grammatical because the verb has a direct
+        object, name the nonmutating variant using the verb's present
+        [participle](https://en.wikipedia.org/wiki/Participle), by
+        appending “ing.”
 
-    * Prefer to name the nonmutating variant using the verb's past
-      [participle](https://en.wikipedia.org/wiki/Participle) (usually
-      appending “ed”):
+        ~~~ swift
+        /// Strips all the newlines from `self`
+        mutating func stripNewlines()
 
-      ~~~ swift
-      /// Reverses `self` in-place.
-      mutating func reverse()
-
-      /// Returns a reversed copy of `self`.
-      func revers**ed**() -> Self
-      ...
-      x.reverse()
-      let y = x.reversed()
-      ~~~
+        /// Returns a copy of `self` with all the newlines stripped.
+        func strip**ping**Newlines() -> String
+        ...
+        s.stripNewlines()
+        let oneLine = t.strippingNewlines()
+        ~~~
 
-    * When adding “ed” is not grammatical because the verb has a direct
-      object, name the nonmutating variant using the verb's present
-      [participle](https://en.wikipedia.org/wiki/Participle), by
-      appending “ing.”
+      {{enddetail}}
 
-      ~~~ swift
-      /// Strips all the newlines from \`self\`
-      mutating func stripNewlines()
-
-      /// Returns a copy of \`self\` with all the newlines stripped.
-      func strip**ping**Newlines() -> String
-      ...
-      s.stripNewlines()
-      let oneLine = t.strippingNewlines()
-      ~~~
+    * When the operation is **naturally described by a noun**, use the
+      noun for the nonmutating method and apply the “form” prefix to
+      name its mutating counterpart.
 
-    {{enddetail}}
+      |Nonmutating|Mutating|
+      |-
+      |`x = y.union(z)`|`y.formUnion(z)`|
+      |`j = c.successor(i)`|`c.formSuccessor(&i)`|
 
 * **Uses of Boolean methods and properties should read as assertions
   about the receiver** when the use is nonmutating, e.g. `x.isEmpty`,

css/main.scss

@@ -2,22 +2,18 @@
 # Only the main Sass file needs front matter (the dashes are enough)
 ---
 @import url("http://swift.org/assets/stylesheets/application.css");
-// The following should be moved to the Swift.org stylesheet
-article { 
-    pre.good {
-        background: #E6FFE5;
-        border-color: #C0FFBC;
+// The following has been moved to the Swift.org stylesheet
+td {
+    & > code {
+        color: #000;
+        padding: 3px 8px;
+        font-size: 14px;
+        white-space: nowrap;
+        border: 1px solid #E5E5E5;
+        background-color: rgba(127, 127, 127, 1.0) !important;
     }
-    pre.good:before {
-        content: "✅";
-        float: right;
-    }
-    pre.bad {
-        background: #F9E2E4;
-        border-color: #F6B7BE;
-    }
-    pre.bad:before {
-        content: "⛔️";
-        float: right;
-    }
-}
+}
+
+article table td code {
+    background-color: #f7f7f7 !important;
+}