From 9d27a0143c2d9c8a3a3715e974402d4c5b754c43 Mon Sep 17 00:00:00 2001 From: Laurent Le Brun Date: Tue, 31 Mar 2015 12:28:02 +0000 Subject: Skylark: Improve documentation -- MOS_MIGRATED_REVID=89957248 --- .../devtools/build/lib/packages/MethodLibrary.java | 53 +++++++++++++--------- .../rules/SkylarkRuleImplementationFunctions.java | 1 - 2 files changed, 32 insertions(+), 22 deletions(-) (limited to 'src') 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:
" - + "
\"|\".join([\"a\", \"b\", \"c\"]) == \"a|b|c\"
", + + "
\"|\".join([\"a\", \"b\", \"c\"]) == \"a|b|c\"
", 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:" + + "
"
+          + "{2: \"a\", 4: \"b\", 1: \"c\"}.values() == [\"c\", \"a\", \"b\"]
\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:" + + "
"
+          + "{2: \"a\", 4: \"b\", 1: \"c\"}.items() == [(1, \"c\"), (2, \"a\"), (4, \"b\")]"
+          + "
\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:" + + "
{2: \"a\", 4: \"b\", 1: \"c\"}.keys() == [1, 2, 4]"
+          + "
\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." + + "
list([1, 2]) == [1, 2]\n"
+        + "list(set([2, 3, 2])) == [2, 3]\n"
+        + "list({5: \"a\", 2: \"b\", 4: \"c\"}) == [2, 4, 5]
", 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:
" - + "
s = struct(x = 2, y = 3)\n"
+      + "
s = struct(x = 2, y = 3)\n"
       + "return s.x + s.y  # returns 5
")
   private static Function struct = new AbstractFunction("struct") {
 
@@ -659,7 +669,7 @@ public class MethodLibrary {
       doc = "Creates a set from the items. The set supports nesting other sets of the"
       + " same element type in it. For this reason sets are also referred to as nested sets"
       + " (all Skylark sets are nested sets). A desired iteration order can also be specified.
"
-      + " Examples:
set([1, set([2, 3]), 2])\n"
+      + " Examples:
set([1, set([2, 3]), 2])\n"
       + "set([1, 2, 3], order=\"compile\")
",
       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
"
+          + " the input list.\n
"
           + "enumerate([24, 21, 84]) == [[0, 24], [1, 21], [2, 84]]
\n",
       mandatoryParams = {
       @Param(name = "list", type = SkylarkList.class,
@@ -712,7 +722,7 @@ public class MethodLibrary {
       doc = "Creates a list where items go from start to stop, using a "
           + "step increment. If a single argument is provided, items will "
           + "range from 0 to that element."
-          + "
range(4) == [0, 1, 2, 3]\n"
+          + "
range(4) == [0, 1, 2, 3]\n"
           + "range(3, 9, 2) == [3, 5, 7]\n"
           + "range(3, 0, -1) == [3, 2, 1]
",
       mandatoryParams = {
@@ -786,7 +796,7 @@ public class MethodLibrary {
   @SkylarkBuiltin(name = "hasattr", returnType = Boolean.class,
       doc = "Returns True if the object x has a field of the given name, "
           + "otherwise False. Example:
"
-          + "
hasattr(ctx.attr, \"myattr\")
",
+          + "
hasattr(ctx.attr, \"myattr\")
",
       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, getattr(x, \"foobar\")"
           + " is equivalent to x.foobar."
           + "Example:
"
-          + "
getattr(ctx.attr, \"myattr\")\n"
+          + "
getattr(ctx.attr, \"myattr\")\n"
           + "getattr(ctx.attr, \"myattr\", \"mydefault\")
",
      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:"
-          + "
"
+          + "
"
           + "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:
"
-      + "
a = 'abc\\ndef'\n"
+      + "
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\"
"
       + "Strings are iterable and support the in operator. Examples:
"
-      + "
\"a\" in \"abc\"   # evaluates as True\n"
+      + "
\"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\"]
")
   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:
"
-      + "
d = {\"a\": 2, \"b\": 5}
"
-      + "Accessing elements works just like in Python:
"
-      + "
e = d[\"a\"]   # e == 2
"
+      + "
d = {\"a\": 2, \"b\": 5}
"
+      + "Use brackets to access elements:
"
+      + "
e = d[\"a\"]   # e == 2
"
       + "Dicts support the + operator to concatenate two dicts. In case of multiple "
       + "keys the second one overrides the first one. Examples:
"
-      + "
"
+      + "
"
       + "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}
"
       + "Since the language doesn't have mutable objects d[\"a\"] = 5 automatically "
       + "translates to d = d + {\"a\" : 5}.
"
-      + "Dicts are iterable, the iteration works on their keyset.
"
+      + "Iterating on a dict is equivalent to iterating on its keys (in sorted order).
"
       + "Dicts support the in operator, testing membership in the keyset of the dict. "
       + "Example:
"
-      + "
\"a\" in {\"a\" : 2, \"b\" : 5}   # evaluates as True
")
+      + "
\"a\" in {\"a\" : 2, \"b\" : 5}   # evaluates as True"
+      + "
")
   public static final class DictModule {}
 
   public static final Map 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",
-- 
cgit v1.2.3