Add new names for depset traversal orders

The old names are deprecated but still supported for now. A flag for enforcing the deprecation will come in a later change.

RELNOTES[INC]: The traversal orders for depsets have been renamed. The old names are deprecated and will be removed in the future. New names: "stable" -> "default", "compile" -> "postorder", "link" -> "topological", "naive_link" -> "preorder".

--
PiperOrigin-RevId: 145004718
MOS_MIGRATED_REVID=145004718

1 files changed, 30 insertions, 20 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 23535f6fc3..530efc0994 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
@@ -45,6 +45,7 @@ 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 "
@@ -53,38 +54,47 @@ import javax.annotation.Nullable;
         + "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. 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=\"compile\")</pre>"
+        + "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 or be of type <code>list</code>, "
+        + "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>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>stable</code>: Same behavior as <code>compile</code>.</li>"
-        + "<li><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>)."
+
+        + "<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>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>link</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><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>stable</code>, the above values are incompatible with each other. "
-        + "Consequently, two depsets can only be merged via the <code>|</code> operator or via "
+
+        + "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 "
@@ -312,7 +322,7 @@ public final class SkylarkNestedSet implements Iterable<Object>, SkylarkValue, S
     Printer.printList(buffer, this, "[", ", ", "]", null, quotationMark);
     Order order = getOrder();
     if (order != Order.STABLE_ORDER) {
-      Printer.append(buffer, ", order = \"" + order.getName() + "\"");
+      Printer.append(buffer, ", order = \"" + order.getSkylarkName() + "\"");
     }
     Printer.append(buffer, ")");
   }