Add more depset documentation

Updated class doc, added examples to depsets.md.

Constructor/method doc updates will be a follow-up CL.

--
PiperOrigin-RevId: 148463032
MOS_MIGRATED_REVID=148463032

1 files changed, 39 insertions, 55 deletions

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 e7efcd301c..902d4a9c1d 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
@@ -44,62 +44,46 @@ import javax.annotation.Nullable;
 @SkylarkModule(
     name = "depset",
     category = SkylarkModuleCategory.BUILTIN,
-    // TODO(bazel-team): Move this documentation to a dedicated page and link to it from here.
     doc =
-        "A language built-in type that supports efficiently accumulating data from transitive "
-        + "dependencies. Note that depsets are not hash sets: they don't support fast membership "
-        + "tests, but on the contrary they support fast union. Depsets are designed to be used as "
-        + "a collection of items (such as file names) generated by Bazel targets. "
-        + "Depsets can be created using the <a href=\"globals.html#depset\">depset</a> function, "
-        + "and they support the <code>+</code> operator to extend the depset with more elements or "
-        + "to nest other depsets inside of it (the <code>|</code> is equivalent). Examples:<br>"
-
-        + "<pre class=language-python>s = depset([1, 2])\n"
-        + "s = s + [3]              # s == {1, 2, 3}\n"
-        + "s = s + depset([4, 5])   # s == {1, 2, 3, {4, 5}}\n"
-        + "other = depset([\"a\", \"b\", \"c\"], order=\"postorder\")</pre>"
-
-        + "Note that in these examples <code>{..}</code> is not a valid literal to create depsets. "
-        + "Depsets have a fixed generic type, so <code>depset([1]) + [\"a\"]</code> or "
-        + "<code>depset([1]) + depset([\"a\"])</code> results in an error.<br>"
-        + "Elements in a depset can neither be mutable nor be of type <code>list</code>, "
-        + "<code>struct</code> or <code>dict</code>.<br>"
-        + "When aggregating data from providers, depsets can take significantly less memory than "
-        + "other types as they support nesting, that is, their subsets are shared in memory.<br>"
-        + "Every depset has an <code>order</code> parameter which determines the iteration order. "
-        + "There are four possible values:"
-
-        + "<ul><li><code>postorder</code> (formerly <code>compile</code>): Defines a left-to-right "
-        + "post-ordering where child elements come after those of nested depsets (parent-last). "
-        + "For example, <code>{1, 2, 3, {4, 5}}</code> leads to <code>4 5 1 2 3</code>. "
-        + "Left-to-right order is preserved for both the child elements and the references to "
-        + "nested depsets.</li>"
-
-        + "<li><code>default</code> (formerly <code>stable</code>): Same behavior as "
-        + "<code>postorder</code>.</li>"
-
-        + "<li><code>topological</code> (formerly <code>link</code>): Defines a variation of "
-        + "left-to-right pre-ordering, i.e. <code>{1, 2, 3, {4, 5}}</code> leads to "
-        + "<code>1 2 3 4 5</code>. This ordering enforces that elements of the depset always come "
-        + "before elements of nested depsets (parent-first), which may lead to situations where "
-        + "left-to-right order cannot be preserved (<a href=\"https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/collect/nestedset/LinkOrderExpander.java#L56\">Example</a>)."
-        + "</li>"
-
-        + "<li><code>preorder</code> (formerly <code>naive_link</code>): Defines \"naive\" "
-        + "left-to-right pre-ordering (parent-first), i.e. <code>{1, 2, 3, {4, 5}}</code> leads to "
-        + "<code>1 2 3 4 5</code>. Unlike <code>topological</code> ordering, it will sacrifice the "
-        + "parent-first property in order to uphold left-to-right order in cases where both "
-        + "properties cannot be 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>default</code>, the above values are incompatible with each other. "
-        + "Consequently, two depsets can only be merged via the <code>+</code> operator or via "
-        + "<code>union()</code> if either both depsets have the same <code>order</code> or one of "
-        + "the depsets has <code>stable</code> order. In the latter case the iteration order will "
-        + "be determined by the outer depset, thus ignoring the <code>order</code> parameter of "
-        + "nested depsets.<br>"
-        + "The function <code>set</code> is a deprecated alias for <code>depset</code>. Please "
-        + "update legacy code and use only <code>depset</code>."
+        "<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>."
 )
 @Immutable
 public final class SkylarkNestedSet implements SkylarkValue, SkylarkQueryable {