Update depset constructor/method docs

--
PiperOrigin-RevId: 148469323
MOS_MIGRATED_REVID=148469323

2 files changed, 61 insertions, 62 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java
index 30b4161d4b..4491380bcc 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java
@@ -56,31 +56,31 @@ public class BazelLibrary {
     name = "depset",
     returnType = SkylarkNestedSet.class,
     doc =
-        "Creates a <a href=\"depset.html\">depset</a> from the <code>items</code>. "
-            + "The depset supports nesting other depsets of the same element type in it. "
-            + "A desired <a href=\"depset.html\">iteration order</a> can also be specified.<br>"
-            + "Examples:<br><pre class=\"language-python\">depset([\"a\", \"b\"])\n"
-            + "depset([1, 2, 3], order=\"postorder\")</pre>",
+        "Creates a <a href=\"depset.html\">depset</a>. In the case that <code>items</code> is an "
+            + "iterable, its contents become the direct elements of the depset, with their left-to-"
+            + "right order preserved, and the depset has no transitive elements. In the case that "
+            + "<code>items</code> is a depset, it is made the sole transitive element of the new "
+            + "depset, and no direct elements are added. In the second case the given depset's "
+            + "order must match the <code>order</code> param or else one of the two must be <code>"
+            + "\"default\"</code>. See the <a href=\"../depsets.md\">Depsets overview</a> for more "
+            + "information.",
     parameters = {
       @Param(
         name = "items",
         type = Object.class,
         defaultValue = "[]",
         doc =
-            "The items to initialize the depset with. May contain both standalone items "
-                + "and other depsets."
+            "An iterable whose items become the direct elements of the new depset, in left-to-"
+                + "right order; or alternatively, a depset that becomes the transitive element of "
+                + "the new depset."
       ),
       @Param(
         name = "order",
         type = String.class,
         defaultValue = "\"default\"",
         doc =
-            "The ordering strategy for the depset. Possible values are: <code>default</code> "
-                + "(default), <code>postorder</code>, <code>topological</code>, and "
-                + "<code>preorder</code>. These are also known by the deprecated names "
-                + "<code>stable</code>, <code>compile</code>, <code>link</code> and "
-                + "<code>naive_link</code> respectively. An explanation of the values can be found "
-                + "<a href=\"depset.html\">here</a>."
+            "The traversal strategy for the new depset. See <a href=\"depset.html\">here</a> for "
+                + "the possible values."
       )
     },
     useLocation = true
@@ -137,8 +137,9 @@ public class BazelLibrary {
     objectType = SkylarkNestedSet.class,
     returnType = SkylarkNestedSet.class,
     doc =
-        "Creates a new <a href=\"depset.html\">depset</a> that contains both "
-            + "the input depset as well as all additional elements.",
+        "<i>(Deprecated)</i> Returns a new <a href=\"depset.html\">depset</a> that is the merge "
+            + "of the given depset and <code>new_elements</code>. This is the same as the <code>+"
+            + "</code> operator.",
     parameters = {
       @Param(name = "input", type = SkylarkNestedSet.class, doc = "The input depset."),
       @Param(name = "new_elements", type = Object.class, doc = "The elements to be added.")
@@ -148,8 +149,7 @@ public class BazelLibrary {
   private static final BuiltinFunction union =
       new BuiltinFunction("union") {
         @SuppressWarnings("unused")
-        public SkylarkNestedSet invoke(
-            SkylarkNestedSet input, Object newElements, Location loc)
+        public SkylarkNestedSet invoke(SkylarkNestedSet input, Object newElements, Location loc)
             throws EvalException {
           // newElements' type is Object because of the polymorphism on unioning two
           // SkylarkNestedSets versus a set and another kind of iterable.
@@ -182,8 +182,8 @@ public class BazelLibrary {
             throws EvalException {
           for (Object key : dict.keySet()) {
             if (!(key instanceof String)) {
-              throw new EvalException(loc,
-                  String.format("Invalid key: %s. select keys must be label references", key));
+              throw new EvalException(
+                  loc, String.format("Invalid key: %s. select keys must be label references", key));
             }
           }
           return SelectorList.of(new SelectorValue(dict, noMatchError));
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java
index 902d4a9c1d..92b0060cc5 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java
@@ -39,51 +39,50 @@ import javax.annotation.Nullable;
  *
  * <p>It is also an error if this type has a non-bottom intersection with {@link SkylarkType#DICT}
  * or {@link SkylarkType#LIST}, unless the set is empty.
- * TODO(bazel-team): Decide whether this restriction is still useful.
+ *
+ * <p>TODO(bazel-team): Decide whether this restriction is still useful.
  */
 @SkylarkModule(
-    name = "depset",
-    category = SkylarkModuleCategory.BUILTIN,
-    doc =
-        "<p>A specialized data structure that supports efficient merge operations and has a "
-        + "defined traversal order. Commonly used for accumulating data from transitive "
-        + "dependencies in rules and aspects. For more information see "
-        + "<a href=\"../depsets.html\">here</a>."
-
-        + "<p>Depsets are not implemented as hash sets and do not support fast membership tests. "
-        + "If you need a general set datatype, you can simulate one using a dictionary where all "
-        + "keys map to <code>None</code>."
-
-        + "<p>Depsets are immutable. They can be created using their "
-        + "<a href=\"globals.html#depset\">constructor function</a> and merged or augmented using "
-        + "the <code>+</code> operator."
-
-        + "<p>The <code>order</code> parameter determines the kind of traversal that is done to "
-        + "convert the depset to an iterable. There are four possible values:"
-
-        + "<ul>"
-        + "<li><code>default</code> (formerly <code>stable</code>): Order is unspecified (but "
-        + "deterministic).</li>"
-
-        + "<li><code>postorder</code> (formerly <code>compile</code>): A left-to-right post-"
-        + "ordering. Precisely, this recursively traverses all children leftmost-first, then the "
-        + "direct elements leftmost-first.</li>"
-
-        + "<li><code>preorder</code> (formerly <code>naive_link</code>): A left-to-right pre-"
-        + "ordering. Precisely, this traverses the direct elements leftmost-first, then "
-        + "recursively traverses the children leftmost-first.</li>"
-
-        + "<li><code>topological</code> (formerly <code>link</code>): A topological ordering from "
-        + "the root down to the leaves. There is no left-to-right guarantee.</li>"
-        + "</ul>"
-
-        + "<p>Two depsets may only be merged (via <code>+</code> or the <code>union()</code> "
-        + "method) if either both depsets have the same order, or one of them has <code>stable"
-        + "</code> order. In the latter case the resulting depset's order will be the same as the "
-        + "left operand's."
-
-        + "<p>The function <code>set()</code> is a deprecated alias for <code>depset()</code>. "
-        + "Please update legacy code and use only <code>depset()</code>."
+  name = "depset",
+  category = SkylarkModuleCategory.BUILTIN,
+  doc =
+      "<p>A specialized data structure that supports efficient merge operations and has a defined "
+          + "traversal order. Commonly used for accumulating data from transitive dependencies in "
+          + "rules and aspects. For more information see <a href=\"../depsets.md\">here</a>."
+          + "<p>"
+          + "Depsets are not implemented as hash sets and do not support fast membership tests. If "
+          + "you need a general set datatype, you can simulate one using a dictionary where all "
+          + "keys map to <code>None</code>."
+          + "<p>"
+          + "Depsets are immutable. They can be created using their "
+          + "<a href=\"globals.html#depset\">constructor function</a> and merged or augmented "
+          + "using the <code>+</code> operator."
+          + "<p>"
+          + "The <code>order</code> parameter determines the kind of traversal that is done to "
+          + "convert the depset to an iterable. There are four possible values:"
+          + "<ul>"
+          + "<li><code>\"default\"</code> (formerly <code>\"stable\"</code>): Order is unspecified "
+          + "(but deterministic).</li>"
+          + "<li><code>\"postorder\"</code> (formerly <code>\"compile\"</code>): A left-to-right "
+          + "post-ordering. Precisely, this recursively traverses all children leftmost-first, "
+          + "then the direct elements leftmost-first.</li>"
+          + "<li><code>\"preorder\"</code> (formerly <code>\"naive_link\"</code>): A left-to-right "
+          + "pre-ordering. Precisely, this traverses the direct elements leftmost-first, then "
+          + "recursively traverses the children leftmost-first.</li>"
+          + "<li><code>\"topological\"</code> (formerly <code>\"link\"</code>): A topological "
+          + "ordering from the root down to the leaves. There is no left-to-right guarantee.</li>"
+          + "</ul>"
+          + "<p>"
+          + "Two depsets may only be merged (via <code>+</code> or the <code>union()</code> "
+          + "method) if either both depsets have the same order, or one of them has <code>"
+          + "\"default\"</code> order. In the latter case the resulting depset's order will be the "
+          + "same as the left operand's."
+          + "<p>"
+          + "Depsets may contain duplicate values but these will be suppressed when iterating "
+          + "(using <code>to_list()</code>). Duplicates may interfere with the ordering semantics."
+          + "<p>"
+          + "The function <code>set()</code> is a deprecated alias for <code>depset()</code>. "
+          + "Please update legacy code and use only <code>depset()</code>."
 )
 @Immutable
 public final class SkylarkNestedSet implements SkylarkValue, SkylarkQueryable {