diff options
author | 2015-03-31 12:28:02 +0000 | |
---|---|---|
committer | 2015-03-31 14:02:57 +0000 | |
commit | 9d27a0143c2d9c8a3a3715e974402d4c5b754c43 (patch) | |
tree | 65de77bd214ede791acba85e0966c83bfe394f3c /src/main/java/com/google/devtools/build | |
parent | 1b0a8b357cd7d232b8a91b9e7a2db17f2609d156 (diff) |
Skylark: Improve documentation
--
MOS_MIGRATED_REVID=89957248
Diffstat (limited to 'src/main/java/com/google/devtools/build')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java | 53 | ||||
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java | 1 |
2 files changed, 32 insertions, 22 deletions
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 8dd77e16d8..54276d8019 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 @@ public class MethodLibrary { @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 @@ public class MethodLibrary { }; @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 @@ public class MethodLibrary { }; @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 @@ public class MethodLibrary { }; @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 @@ public class MethodLibrary { }; @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 @@ public class MethodLibrary { @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 @@ public class MethodLibrary { 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 @@ public class MethodLibrary { @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 @@ public class MethodLibrary { 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 @@ public class MethodLibrary { @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 @@ public class MethodLibrary { + " 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 @@ public class MethodLibrary { + "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 @@ public class MethodLibrary { @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 @@ public class MethodLibrary { + "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 @@ public class MethodLibrary { @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 diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java index de9ba28eec..b7767b1a93 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java @@ -71,7 +71,6 @@ public class SkylarkRuleImplementationFunctions { * arguments = [argument1, argument2, ...], * mnemonic = 'mnemonic', * command = 'command', - * register = 1 * ) */ @SkylarkBuiltin(name = "action", |