Skylark: Improve documentation
--
MOS_MIGRATED_REVID=89957248
diff --git a/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java
index 8dd77e1..54276d8 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java
@@ -108,7 +108,7 @@
@SkylarkBuiltin(name = "join", objectType = StringModule.class, returnType = String.class,
doc = "Returns a string in which the string elements of the argument have been "
+ "joined by this string as a separator. Example:<br>"
- + "<pre class=language-python>\"|\".join([\"a\", \"b\", \"c\"]) == \"a|b|c\"</pre>",
+ + "<pre class=\"language-python\">\"|\".join([\"a\", \"b\", \"c\"]) == \"a|b|c\"</pre>",
mandatoryParams = {
@Param(name = "elements", type = SkylarkList.class, doc = "The objects to join.")})
private static Function join = new MixedModeFunction("join",
@@ -525,7 +525,9 @@
};
@SkylarkBuiltin(name = "values", objectType = DictModule.class, returnType = SkylarkList.class,
- doc = "Return the list of values.")
+ doc = "Return the list of values. Dictionaries are always sorted by their keys:"
+ + "<pre class=\"language-python\">"
+ + "{2: \"a\", 4: \"b\", 1: \"c\"}.values() == [\"c\", \"a\", \"b\"]</pre>\n")
private static Function values = new NoArgFunction("values") {
@Override
public Object call(Object self, FuncallExpression ast, Environment env)
@@ -537,7 +539,10 @@
};
@SkylarkBuiltin(name = "items", objectType = DictModule.class, returnType = SkylarkList.class,
- doc = "Return the list of key-value tuples.")
+ doc = "Return the list of key-value tuples. Dictionaries are always sorted by their keys:"
+ + "<pre class=\"language-python\">"
+ + "{2: \"a\", 4: \"b\", 1: \"c\"}.items() == [(1, \"c\"), (2, \"a\"), (4, \"b\")]"
+ + "</pre>\n")
private static Function items = new NoArgFunction("items") {
@Override
public Object call(Object self, FuncallExpression ast, Environment env)
@@ -554,7 +559,9 @@
};
@SkylarkBuiltin(name = "keys", objectType = DictModule.class, returnType = SkylarkList.class,
- doc = "Return the list of keys.")
+ doc = "Return the list of keys. Dictionaries are always sorted by their keys:"
+ + "<pre class=\"language-python\">{2: \"a\", 4: \"b\", 1: \"c\"}.keys() == [1, 2, 4]"
+ + "</pre>\n")
private static Function keys = new NoArgFunction("keys") {
@Override
public Object call(Object self, FuncallExpression ast, Environment env)
@@ -586,7 +593,10 @@
};
@SkylarkBuiltin(name = "list", returnType = SkylarkList.class,
- doc = "Converts a collection (e.g. set or dictionary) to a list.",
+ doc = "Converts a collection (e.g. set or dictionary) to a list."
+ + "<pre class=\"language-python\">list([1, 2]) == [1, 2]\n"
+ + "list(set([2, 3, 2])) == [2, 3]\n"
+ + "list({5: \"a\", 2: \"b\", 4: \"c\"}) == [2, 4, 5]</pre>",
mandatoryParams = {@Param(name = "x", doc = "The object to convert.")})
private static Function list = new MixedModeFunction("list",
ImmutableList.of("list"), 1, false) {
@@ -641,7 +651,7 @@
@SkylarkBuiltin(name = "struct", returnType = SkylarkClassObject.class, doc =
"Creates an immutable struct using the keyword arguments as fields. It is used to group "
+ "multiple values together.Example:<br>"
- + "<pre class=language-python>s = struct(x = 2, y = 3)\n"
+ + "<pre class=\"language-python\">s = struct(x = 2, y = 3)\n"
+ "return s.x + s.y # returns 5</pre>")
private static Function struct = new AbstractFunction("struct") {
@@ -659,7 +669,7 @@
doc = "Creates a set from the <code>items</code>. The set supports nesting other sets of the"
+ " same element type in it. For this reason sets are also referred to as <i>nested sets</i>"
+ " (all Skylark sets are nested sets). A desired iteration order can also be specified.<br>"
- + " Examples:<br><pre class=language-python>set([1, set([2, 3]), 2])\n"
+ + " Examples:<br><pre class=\"language-python\">set([1, set([2, 3]), 2])\n"
+ "set([1, 2, 3], order=\"compile\")</pre>",
optionalParams = {
@Param(name = "items", type = SkylarkList.class,
@@ -684,7 +694,7 @@
@SkylarkBuiltin(name = "enumerate", returnType = SkylarkList.class,
doc = "Return a list of pairs (two-element lists), with the index (int) and the item from"
- + " the input list.\n<pre class=language-python>"
+ + " the input list.\n<pre class=\"language-python\">"
+ "enumerate([24, 21, 84]) == [[0, 24], [1, 21], [2, 84]]</pre>\n",
mandatoryParams = {
@Param(name = "list", type = SkylarkList.class,
@@ -712,7 +722,7 @@
doc = "Creates a list where items go from <code>start</code> to <code>stop</code>, using a "
+ "<code>step</code> increment. If a single argument is provided, items will "
+ "range from 0 to that element."
- + "<pre class=language-python>range(4) == [0, 1, 2, 3]\n"
+ + "<pre class=\"language-python\">range(4) == [0, 1, 2, 3]\n"
+ "range(3, 9, 2) == [3, 5, 7]\n"
+ "range(3, 0, -1) == [3, 2, 1]</pre>",
mandatoryParams = {
@@ -786,7 +796,7 @@
@SkylarkBuiltin(name = "hasattr", returnType = Boolean.class,
doc = "Returns True if the object <code>x</code> has a field of the given <code>name</code>, "
+ "otherwise False. Example:<br>"
- + "<pre class=language-python>hasattr(ctx.attr, \"myattr\")</pre>",
+ + "<pre class=\"language-python\">hasattr(ctx.attr, \"myattr\")</pre>",
mandatoryParams = {
@Param(name = "object", doc = "The object to check."),
@Param(name = "name", type = String.class, doc = "The name of the field.")})
@@ -821,7 +831,7 @@
+ " if specified, otherwise rasies an error. For example, <code>getattr(x, \"foobar\")"
+ "</code> is equivalent to <code>x.foobar</code>."
+ "Example:<br>"
- + "<pre class=language-python>getattr(ctx.attr, \"myattr\")\n"
+ + "<pre class=\"language-python\">getattr(ctx.attr, \"myattr\")\n"
+ "getattr(ctx.attr, \"myattr\", \"mydefault\")</pre>",
mandatoryParams = {
@Param(name = "object", doc = "The struct which's field is accessed."),
@@ -957,7 +967,7 @@
+ "the i-th element from each of the argument sequences or iterables. The list has the "
+ "size of the shortest input. With a single iterable argument, it returns a list of "
+ "1-tuples. With no arguments, it returns an empty list. Examples:"
- + "<pre class=language-python>"
+ + "<pre class=\"language-python\">"
+ "zip() # == []\n"
+ "zip([1, 2]) # == [(1,), (2,)]\n"
+ "zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)]\n"
@@ -997,7 +1007,7 @@
@SkylarkModule(name = "string", doc =
"A language built-in type to support strings. "
+ "Examples of string literals:<br>"
- + "<pre class=language-python>a = 'abc\\ndef'\n"
+ + "<pre class=\"language-python\">a = 'abc\\ndef'\n"
+ "b = \"ab'cd\"\n"
+ "c = \"\"\"multiline string\"\"\"\n"
+ "\n"
@@ -1006,9 +1016,9 @@
+ "y = \"hello\"[1:-1] # \"ell\"\n"
+ "z = \"hello\"[:4] # \"hell\"</pre>"
+ "Strings are iterable and support the <code>in</code> operator. Examples:<br>"
- + "<pre class=language-python>\"a\" in \"abc\" # evaluates as True\n"
+ + "<pre class=\"language-python\">\"a\" in \"abc\" # evaluates as True\n"
+ "x = []\n"
- + "for s in \"abc\":\n"
+ + "for s in \"abc\":\n"
+ " x += [s] # x == [\"a\", \"b\", \"c\"]</pre>")
public static final class StringModule {}
@@ -1018,21 +1028,22 @@
@SkylarkModule(name = "dict", doc =
"A language built-in type to support dicts. "
+ "Example of dict literal:<br>"
- + "<pre class=language-python>d = {\"a\": 2, \"b\": 5}</pre>"
- + "Accessing elements works just like in Python:<br>"
- + "<pre class=language-python>e = d[\"a\"] # e == 2</pre>"
+ + "<pre class=\"language-python\">d = {\"a\": 2, \"b\": 5}</pre>"
+ + "Use brackets to access elements:<br>"
+ + "<pre class=\"language-python\">e = d[\"a\"] # e == 2</pre>"
+ "Dicts support the <code>+</code> operator to concatenate two dicts. In case of multiple "
+ "keys the second one overrides the first one. Examples:<br>"
- + "<pre class=language-python>"
+ + "<pre class=\"language-python\">"
+ "d = {\"a\" : 1} + {\"b\" : 2} # d == {\"a\" : 1, \"b\" : 2}\n"
+ "d += {\"c\" : 3} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 3}\n"
+ "d = d + {\"c\" : 5} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 5}</pre>"
+ "Since the language doesn't have mutable objects <code>d[\"a\"] = 5</code> automatically "
+ "translates to <code>d = d + {\"a\" : 5}</code>.<br>"
- + "Dicts are iterable, the iteration works on their keyset.<br>"
+ + "Iterating on a dict is equivalent to iterating on its keys (in sorted order).<br>"
+ "Dicts support the <code>in</code> operator, testing membership in the keyset of the dict. "
+ "Example:<br>"
- + "<pre class=language-python>\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True</pre>")
+ + "<pre class=\"language-python\">\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True"
+ + "</pre>")
public static final class DictModule {}
public static final Map<Function, SkylarkType> stringFunctions = ImmutableMap
