Documentation fixes.

--
MOS_MIGRATED_REVID=94274751

4 files changed, 19 insertions, 12 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 8de762c0be..9aa630717b 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
@@ -689,7 +689,7 @@ public class MethodLibrary {
   @SkylarkSignature(name = "bool", returnType = Boolean.class,
       doc = "Converts an object to boolean. "
       + "It returns False if the object is None, False, an empty string, the number 0, or an "
-      + "empty collection. Otherwise, it returns True. Similarly to Python <code>bool</code> "
+      + "empty collection. Otherwise, it returns True. As in Python, <code>bool</code> "
       + "is also a type.",
       mandatoryPositionals = {@Param(name = "x", doc = "The variable to convert.")})
   private static BuiltinFunction bool = new BuiltinFunction("bool") {
@@ -766,9 +766,9 @@ public class MethodLibrary {
   };
 
   @SkylarkSignature(name = "enumerate",  returnType = SkylarkList.class,
-      doc = "Return a list of pairs (two-element lists), with the index (int) and the item from"
+      doc = "Return a list of pairs (two-element tuples), with the index (int) and the item from"
           + " the input list.\n<pre class=\"language-python\">"
-          + "enumerate([24, 21, 84]) == [[0, 24], [1, 21], [2, 84]]</pre>\n",
+          + "enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]</pre>\n",
       mandatoryPositionals = {@Param(name = "list", type = SkylarkList.class, doc = "input list")},
       useLocation = true)
   private static BuiltinFunction enumerate = new BuiltinFunction("enumerate") {
@@ -880,13 +880,14 @@ public class MethodLibrary {
 
   @SkylarkSignature(name = "getattr",
       doc = "Returns the struct's field of the given name if exists, otherwise <code>default</code>"
-          + " if specified, otherwise rasies an error. For example, <code>getattr(x, \"foobar\")"
-          + "</code> is equivalent to <code>x.foobar</code>."
-          + "Example:<br>"
+          + " if specified, otherwise raises an error. For example, <code>getattr(x, \"foobar\")"
+          + "</code> is equivalent to <code>x.foobar</code>, except that it returns "
+          + "<code>default</code> for a non-existant attribute instead of raising an error."
+          + "<br>"
           + "<pre class=\"language-python\">getattr(ctx.attr, \"myattr\")\n"
           + "getattr(ctx.attr, \"myattr\", \"mydefault\")</pre>",
       mandatoryPositionals = {
-        @Param(name = "object", doc = "The struct which's field is accessed."),
+        @Param(name = "object", doc = "The struct whose field is accessed."),
         @Param(name = "name", doc = "The name of the struct field.")},
       optionalPositionals = {
         @Param(name = "default", defaultValue = "None",
@@ -1041,8 +1042,10 @@ public class MethodLibrary {
       + "Strings are iterable and support the <code>in</code> operator. Examples:<br>"
       + "<pre class=\"language-python\">\"a\" in \"abc\"   # evaluates as True\n"
       + "x = []\n"
-     + "for s in \"abc\":\n"
-      + "  x += [s]     # x == [\"a\", \"b\", \"c\"]</pre>")
+      + "for s in \"abc\":\n"
+      + "  x += [s]     # x == [\"a\", \"b\", \"c\"]</pre>\n"
+      + "Implicit concatenation of strings is not allowed; use the <code>+</code> "
+      + "operator instead.")
   public static final class StringModule {}
 
   /**
diff --git a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
index 1965b9d91c..53cacb1227 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java
@@ -71,7 +71,7 @@ public class SkylarkNativeModule {
           + "The label can be referenced in <code>visibility</code> attributes.",
       mandatoryNamedOnly = {
       @Param(name = "name", type = String.class,
-          doc = "A unique name for this rule.")},
+          doc = "The unique name for this rule.")},
       optionalNamedOnly = {
       @Param(name = "packages", type = SkylarkList.class, generic1 = String.class,
           defaultValue = "[]",
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
index f436b1d06b..797c2bfaa2 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
@@ -196,7 +196,11 @@ public class SkylarkRuleClassFunctions {
             "dictionary to declare all the attributes of the rule. It maps from an attribute name "
             + "to an attribute object (see <a href=\"#modules.attr\">attr</a> module). "
             + "Attributes starting with <code>_</code> are private, and can be used to add "
-            + "an implicit dependency on a label."),
+            + "an implicit dependency on a label. The attribute <code>name</code> is implicitly "
+            + "added and must not be specified. Attributes <code>visibility</code>, "
+            + "<code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and "
+            + "<code>features</code> are implicitly added and might be overriden."),
+            // TODO(bazel-team): need to give the types of these builtin attributes
         @Param(name = "outputs", type = Map.class, callbackEnabled = true, noneable = true,
             defaultValue = "None", doc = "outputs of this rule. "
             + "It is a dictionary mapping from string to a template name. "
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
index 91a0e81a65..e671ad1eec 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
@@ -471,7 +471,7 @@ public final class SkylarkRuleContext {
 
   @SkylarkCallable(doc =
         "Returns a string after expanding all references to \"Make variables\". The variables "
-      + "have to have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME"
+      + "must have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME"
       + "</code> expands to <code>$VAR_NAME</code>. Parameters:"
       + "<ul><li>The name of the attribute (<code>string</code>). It's only used for error "
       + "reporting.</li>\n"