Minor improvements to set documentation.

--
MOS_MIGRATED_REVID=105591091

src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java

@@ -1248,11 +1248,13 @@ public SkylarkClassObject invoke(Map<String, Object> kwargs, Location loc)
     }
   };
 
-  @SkylarkSignature(name = "set", returnType = SkylarkNestedSet.class,
-      doc = "Creates a <a href=\"set.html\">set</a> from the <code>items</code>."
-      + " The set supports nesting other sets of the same element"
-      + " type in it. A desired iteration order can also be specified.<br>"
-      + " Examples:<br><pre class=\"language-python\">set([\"a\", \"b\"])\n"
+  @SkylarkSignature(
+      name = "set",
+      returnType = SkylarkNestedSet.class,
+      doc = "Creates a <a href=\"set.html\">set</a> from the <code>items</code>. "
+      + "The set supports nesting other sets of the same element type in it. "
+      + "A desired <a href=\"set.html\">iteration order</a> can also be specified.<br>"
+      + "Examples:<br><pre class=\"language-python\">set([\"a\", \"b\"])\n"
       + "set([1, 2, 3], order=\"compile\")</pre>",
       optionalPositionals = {
         @Param(name = "items", type = Object.class, defaultValue = "[]",

src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java

@@ -40,15 +40,16 @@
         + "to nest other sets inside of it. Examples:<br>"
         + "<pre class=language-python>s = set([1, 2])\n"
         + "s = s | [3]           # s == {1, 2, 3}\n"
-        + "s = s | set([4, 5])   # s == {1, 2, 3, {4, 5}}</pre>"
+        + "s = s | set([4, 5])   # s == {1, 2, 3, {4, 5}}\n"
+        + "other = set([\"a\", \"b\", \"c\"], order=\"compile\")</pre>"
         + "Note that in these examples <code>{..}</code> is not a valid literal to create sets. "
         + "Sets have a fixed generic type, so <code>set([1]) + [\"a\"]</code> or "
         + "<code>set([1]) + set([\"a\"])</code> results in an error.<br>"
         + "Elements in a set can neither be mutable or be of type <code>list</code>, "
         + "<code>map</code> or <code>dict</code>.<br>"
         + "When aggregating data from providers, sets can take significantly less memory than "
         + "other types as they support nesting, that is, their subsets are shared in memory.<br>"
-        + "Every set has an <code>order</code> parameter which determines the iteration order."
+        + "Every set has an <code>order</code> parameter which determines the iteration order. "
         + "There are four possible values:"
         + "<ul><li><code>compile</code>: Defines a left-to-right post-ordering where child "
         + "elements come after those of nested sets (parent-last). For example, "
@@ -68,7 +69,7 @@
         + "guaranteed (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/NaiveLinkOrderExpander.java#L26\">Example</a>)."
         + "</li></ul>"
         + "Except for <code>stable</code>, the above values are incompatible with each other. "
-        + "Consequently, two sets can only be merged via the <code>+</code> operator or via "
+        + "Consequently, two sets can only be merged via the <code>|</code> operator or via "
         + "<code>union()</code> if either both sets have the same <code>order</code> or one of "
         + "the sets has <code>stable</code> order. In the latter case the iteration order will be "
         + "determined by the outer set, thus ignoring the <code>order</code> parameter of "