From 50ca4b6012c48c1a414c6fe3f6aaa34f70a17611 Mon Sep 17 00:00:00 2001 From: Jon Brandvein Date: Fri, 24 Feb 2017 17:37:56 +0000 Subject: Update depset constructor/method docs -- PiperOrigin-RevId: 148469323 MOS_MIGRATED_REVID=148469323 --- .../devtools/build/lib/syntax/BazelLibrary.java | 38 +++++----- .../build/lib/syntax/SkylarkNestedSet.java | 85 +++++++++++----------- 2 files changed, 61 insertions(+), 62 deletions(-) (limited to 'src/main/java/com/google/devtools/build') 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 depset from the items. " - + "The depset supports nesting other depsets of the same element type in it. " - + "A desired iteration order can also be specified.
" - + "Examples:
depset([\"a\", \"b\"])\n"
-            + "depset([1, 2, 3], order=\"postorder\")
", + "Creates a depset. In the case that items 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 " + + "items 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 order param or else one of the two must be " + + "\"default\". See the Depsets overview 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: default " - + "(default), postorder, topological, and " - + "preorder. These are also known by the deprecated names " - + "stable, compile, link and " - + "naive_link respectively. An explanation of the values can be found " - + "here." + "The traversal strategy for the new depset. See here for " + + "the possible values." ) }, useLocation = true @@ -137,8 +137,9 @@ public class BazelLibrary { objectType = SkylarkNestedSet.class, returnType = SkylarkNestedSet.class, doc = - "Creates a new depset that contains both " - + "the input depset as well as all additional elements.", + "(Deprecated) Returns a new depset that is the merge " + + "of the given depset and new_elements. This is the same as the +" + + " 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; * *

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. + * + *

TODO(bazel-team): Decide whether this restriction is still useful. */ @SkylarkModule( - name = "depset", - category = SkylarkModuleCategory.BUILTIN, - doc = - "

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 " - + "here." - - + "

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 None." - - + "

Depsets are immutable. They can be created using their " - + "constructor function and merged or augmented using " - + "the + operator." - - + "

The order parameter determines the kind of traversal that is done to " - + "convert the depset to an iterable. There are four possible values:" - - + "

" - - + "

Two depsets may only be merged (via + or the union() " - + "method) if either both depsets have the same order, or one of them has stable" - + " order. In the latter case the resulting depset's order will be the same as the " - + "left operand's." - - + "

The function set() is a deprecated alias for depset(). " - + "Please update legacy code and use only depset()." + name = "depset", + category = SkylarkModuleCategory.BUILTIN, + doc = + "

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 here." + + "

" + + "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 None." + + "

" + + "Depsets are immutable. They can be created using their " + + "constructor function and merged or augmented " + + "using the + operator." + + "

" + + "The order parameter determines the kind of traversal that is done to " + + "convert the depset to an iterable. There are four possible values:" + + "

" + + "

" + + "Two depsets may only be merged (via + or the union() " + + "method) if either both depsets have the same order, or one of them has " + + "\"default\" order. In the latter case the resulting depset's order will be the " + + "same as the left operand's." + + "

" + + "Depsets may contain duplicate values but these will be suppressed when iterating " + + "(using to_list()). Duplicates may interfere with the ordering semantics." + + "

" + + "The function set() is a deprecated alias for depset(). " + + "Please update legacy code and use only depset()." ) @Immutable public final class SkylarkNestedSet implements SkylarkValue, SkylarkQueryable { -- cgit v1.2.3