diff options
Diffstat (limited to 'src/main/java/com/google')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java | 38 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/syntax/SkylarkNestedSet.java | 85 |
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 { |