Enforce @SkylarkCallable must have a non-empty doc string or explicitly be documented=false.

RELNOTES: None.
PiperOrigin-RevId: 191112140

13 files changed, 85 insertions, 46 deletions

diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/SkylarkCallableProcessorTest.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/SkylarkCallableProcessorTest.java
index 36507cb19c..524b356d73 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/SkylarkCallableProcessorTest.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/SkylarkCallableProcessorTest.java
@@ -78,6 +78,15 @@ public final class SkylarkCallableProcessorTest {
   }
 
   @Test
+  public void testDocumentationMissing() throws Exception {
+    assertAbout(javaSource())
+        .that(getFile("DocumentationMissing.java"))
+        .processedWith(new SkylarkCallableProcessor())
+        .failsToCompile()
+        .withErrorContaining("The 'doc' string must be non-empty if 'documented' is true.");
+  }
+
+  @Test
   public void testArgumentMissing() throws Exception {
     assertAbout(javaSource())
         .that(getFile("ArgumentMissing.java"))
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ArgumentMissing.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ArgumentMissing.java
index 00045c303a..9265adc7e2 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ArgumentMissing.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ArgumentMissing.java
@@ -25,7 +25,7 @@ public class ArgumentMissing {
 
   @SkylarkCallable(
     name = "method_with_params",
-    doc = "",
+    documented = false,
     parameters = {
       @Param(name = "a_parameter", type = String.class, named = true),
     })
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/DocumentationMissing.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/DocumentationMissing.java
new file mode 100644
index 0000000000..5efd975279
--- /dev/null
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/DocumentationMissing.java
@@ -0,0 +1,29 @@
+// Copyright 2018 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.devtools.build.lib.skylarkinterface.processor.testsources;
+
+import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
+
+/**
+ * Test case for a SkylarkCallable method which has no documentation and is not explicitly marked
+ * "documented=false".
+ */
+public class DocumentationMissing {
+
+  @SkylarkCallable(name = "undocumented_method")
+  public String undocumentedMethod() {
+    return "fox";
+  }
+}
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/EnvironmentMissing.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/EnvironmentMissing.java
index 47bc416a47..405dc6dfb4 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/EnvironmentMissing.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/EnvironmentMissing.java
@@ -22,7 +22,7 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
  */
 public class EnvironmentMissing {
 
-  @SkylarkCallable(name = "three_arg_method_missing_env", doc = "", useEnvironment = true)
+  @SkylarkCallable(name = "three_arg_method_missing_env", documented = false, useEnvironment = true)
   public String threeArgMethod(String one, Integer two, String three) {
     return "bar";
   }
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/GoldenCase.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/GoldenCase.java
index e20c99bbc7..1c29312db1 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/GoldenCase.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/GoldenCase.java
@@ -29,7 +29,7 @@ public class GoldenCase {
 
   @SkylarkCallable(
     name = "struct_field_method",
-    doc = "",
+    documented = false,
     structField = true)
   public String structFieldMethod() {
     return "foo";
@@ -37,7 +37,7 @@ public class GoldenCase {
 
   @SkylarkCallable(
     name = "struct_field_method_with_info",
-    doc = "",
+    documented = false,
     structField = true,
     useSkylarkSemantics = true
   )
@@ -47,19 +47,20 @@ public class GoldenCase {
 
   @SkylarkCallable(
     name = "zero_arg_method",
-    doc = "")
+    documented = false)
   public Integer zeroArgMethod() {
     return 0;
   }
 
-  @SkylarkCallable(name = "zero_arg_method_with_environment", doc = "", useEnvironment = true)
+  @SkylarkCallable(name = "zero_arg_method_with_environment", documented = false,
+      useEnvironment = true)
   public Integer zeroArgMethod(Environment environment) {
     return 0;
   }
 
   @SkylarkCallable(
     name = "zero_arg_method_with_skylark_info",
-    doc = "",
+    documented = false,
     useAst = true,
     useLocation = true,
     useEnvironment = true,
@@ -75,19 +76,19 @@ public class GoldenCase {
 
   @SkylarkCallable(
     name = "three_arg_method",
-    doc = "")
+    documented = false)
   public String threeArgMethod(String one, Integer two, String three) {
     return "bar";
   }
 
-  @SkylarkCallable(name = "three_arg_method_with_ast", doc = "", useAst = true)
+  @SkylarkCallable(name = "three_arg_method_with_ast", documented = false, useAst = true)
   public String threeArgMethod(String one, Integer two, String three, FuncallExpression ast) {
     return "bar";
   }
 
   @SkylarkCallable(
     name = "three_arg_method_with_params",
-    doc = "",
+    documented = false,
     parameters = {
       @Param(name = "one", type = String.class, named = true),
       @Param(name = "two", type = Integer.class, named = true),
@@ -104,7 +105,7 @@ public class GoldenCase {
 
   @SkylarkCallable(
     name = "three_arg_method_with_params_and_info",
-    doc = "",
+    documented = false,
     parameters = {
       @Param(name = "one", type = String.class, named = true),
       @Param(name = "two", type = Integer.class, named = true),
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/InvalidParamNoneDefault.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/InvalidParamNoneDefault.java
index d74cd631c4..a34cb5c5c6 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/InvalidParamNoneDefault.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/InvalidParamNoneDefault.java
@@ -25,7 +25,7 @@ public class InvalidParamNoneDefault {
 
   @SkylarkCallable(
       name = "method_with_invalid_default",
-      doc = "",
+      documented = false,
       parameters = {
           @Param(name = "a_parameter", type = String.class, named = true, defaultValue = "None"),
       })
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/LocationMissing.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/LocationMissing.java
index 6fd2ef3cb5..ee92215d82 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/LocationMissing.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/LocationMissing.java
@@ -25,7 +25,7 @@ public class LocationMissing {
 
   @SkylarkCallable(
     name = "three_arg_method_missing_location",
-    doc = "",
+    documented = false,
     useLocation = true,
     useEnvironment = true
   )
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ParamTypeConflict.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ParamTypeConflict.java
index cda282f9ac..a3b601d664 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ParamTypeConflict.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/ParamTypeConflict.java
@@ -26,7 +26,7 @@ public class ParamTypeConflict {
 
   @SkylarkCallable(
     name = "param_type_conflict",
-    doc = "",
+    documented = false,
     parameters = {
       @Param(name = "a_parameter",
           type = String.class,
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoBeforeParams.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoBeforeParams.java
index d52605a2ab..0f093d83eb 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoBeforeParams.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoBeforeParams.java
@@ -26,7 +26,7 @@ public class SkylarkInfoBeforeParams {
 
   @SkylarkCallable(
     name = "skylark_info_wrong_order",
-    doc = "",
+    documented = false,
     useLocation = true,
     useEnvironment = true
   )
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoParamsWrongOrder.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoParamsWrongOrder.java
index e82b1a1c6c..56710113f7 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoParamsWrongOrder.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/SkylarkInfoParamsWrongOrder.java
@@ -26,7 +26,7 @@ public class SkylarkInfoParamsWrongOrder {
 
   @SkylarkCallable(
     name = "skylark_info_params_wrong_order",
-    doc = "",
+    documented = false,
     useLocation = true,
     useEnvironment = true
   )
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/StructFieldWithInvalidInfo.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/StructFieldWithInvalidInfo.java
index 0c5b9267fe..2843928d5c 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/StructFieldWithInvalidInfo.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/StructFieldWithInvalidInfo.java
@@ -22,7 +22,7 @@ public class StructFieldWithInvalidInfo {
 
   @SkylarkCallable(
     name = "struct_field_method_with_info",
-    doc = "",
+    documented = false,
     structField = true,
     useEnvironment = true
   )
diff --git a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/TooManyArguments.java b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/TooManyArguments.java
index 81f574ab8f..2c6e17fe91 100644
--- a/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/TooManyArguments.java
+++ b/src/test/java/com/google/devtools/build/lib/skylarkinterface/processor/testsources/TooManyArguments.java
@@ -25,7 +25,7 @@ public class TooManyArguments {
 
   @SkylarkCallable(
     name = "method_with_too_many_arguments",
-    doc = "",
+    documented = false,
     parameters = {
       @Param(name = "parameter_one", type = String.class, named = true),
     })
diff --git a/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java b/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java
index 4a1a09dee7..ed8fb91906 100644
--- a/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java
+++ b/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java
@@ -86,24 +86,24 @@ public class SkylarkEvaluationTest extends EvaluationTest {
       super(CONSTRUCTOR);
     }
 
-    @SkylarkCallable(name = "callable_string", doc = "", structField = false)
+    @SkylarkCallable(name = "callable_string", documented = false, structField = false)
     public String callableString() {
       return "a";
     }
 
-    @SkylarkCallable(name = "struct_field_string", doc = "", structField = true)
+    @SkylarkCallable(name = "struct_field_string", documented = false, structField = true)
     public String structFieldString() {
       return "a";
     }
 
-    @SkylarkCallable(name = "struct_field_callable", doc = "", structField = true)
+    @SkylarkCallable(name = "struct_field_callable", documented = false, structField = true)
     public BuiltinFunction structFieldCallable() {
       return foobar;
     }
 
     @SkylarkCallable(
       name = "struct_field_none",
-      doc = "",
+      documented = false,
       structField = true,
       allowReturnNones = true
     )
@@ -114,58 +114,58 @@ public class SkylarkEvaluationTest extends EvaluationTest {
 
   @SkylarkModule(name = "Mock", doc = "")
   static class Mock {
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public static Integer valueOf(String str) {
       return Integer.valueOf(str);
     }
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public Boolean isEmpty(String str) {
       return str.isEmpty();
     }
     public void value() {}
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public Bad returnBad() {
       return new Bad();
     }
-    @SkylarkCallable(name = "struct_field", doc = "", structField = true)
+    @SkylarkCallable(name = "struct_field", documented = false, structField = true)
     public String structField() {
       return "a";
     }
-    @SkylarkCallable(name = "struct_field_callable", doc = "", structField = true)
+    @SkylarkCallable(name = "struct_field_callable", documented = false, structField = true)
     public BuiltinFunction structFieldCallable() {
       return foobar;
     }
-    @SkylarkCallable(name = "function", doc = "", structField = false)
+    @SkylarkCallable(name = "function", documented = false, structField = false)
     public String function() {
       return "a";
     }
     @SuppressWarnings("unused")
-    @SkylarkCallable(name = "nullfunc_failing", doc = "", allowReturnNones = false)
+    @SkylarkCallable(name = "nullfunc_failing", documented = false, allowReturnNones = false)
     public SkylarkValue nullfuncFailing(String p1, Integer p2) {
       return null;
     }
-    @SkylarkCallable(name = "nullfunc_working", doc = "", allowReturnNones = true)
+    @SkylarkCallable(name = "nullfunc_working", documented = false, allowReturnNones = true)
     public SkylarkValue nullfuncWorking() {
       return null;
     }
-    @SkylarkCallable(name = "voidfunc", doc = "")
+    @SkylarkCallable(name = "voidfunc", documented = false)
     public void voidfunc() {}
-    @SkylarkCallable(name = "string_list", doc = "")
+    @SkylarkCallable(name = "string_list", documented = false)
     public ImmutableList<String> stringList() {
       return ImmutableList.<String>of("a", "b");
     }
-    @SkylarkCallable(name = "string", doc = "")
+    @SkylarkCallable(name = "string", documented = false)
     public String string() {
       return "a";
     }
-    @SkylarkCallable(name = "string_list_dict", doc = "")
+    @SkylarkCallable(name = "string_list_dict", documented = false)
     public Map<String, List<String>> stringListDict() {
       return ImmutableMap.of("a", ImmutableList.of("b", "c"));
     }
 
     @SkylarkCallable(
       name = "with_params",
-      doc = "",
+      documented = false,
       mandatoryPositionals = 1,
       parameters = {
         @Param(name = "pos2", defaultValue = "False", type = Boolean.class),
@@ -241,7 +241,7 @@ public class SkylarkEvaluationTest extends EvaluationTest {
 
     @SkylarkCallable(
       name = "with_extra",
-      doc = "",
+      documented = false,
       useLocation = true,
       useAst = true,
       useEnvironment = true,
@@ -262,7 +262,7 @@ public class SkylarkEvaluationTest extends EvaluationTest {
 
     @SkylarkCallable(
       name = "with_params_and_extra",
-      doc = "",
+      documented = false,
       mandatoryPositionals = 1,
       parameters = {
         @Param(name = "pos2", defaultValue = "False", type = Boolean.class),
@@ -360,7 +360,7 @@ public class SkylarkEvaluationTest extends EvaluationTest {
 
   @SkylarkModule(name = "MockInterface", doc = "")
   static interface MockInterface {
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public Boolean isEmptyInterface(String str);
   }
 
@@ -373,13 +373,13 @@ public class SkylarkEvaluationTest extends EvaluationTest {
     public Boolean isEmptyInterface(String str) {
       return str.isEmpty();
     }
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public Boolean isEmptyClassNotAnnotated(String str) {
       return str.isEmpty();
     }
   }
 
-  @SkylarkModule(name = "MockClassObject", doc = "", documented = false)
+  @SkylarkModule(name = "MockClassObject", documented = false, doc = "")
   static final class MockClassObject implements ClassObject {
     @Override
     public Object getValue(String name) {
@@ -404,10 +404,10 @@ public class SkylarkEvaluationTest extends EvaluationTest {
   @SkylarkModule(name = "MockMultipleMethodClass", doc = "")
   static final class MockMultipleMethodClass {
     @SuppressWarnings("unused")
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public void method(Object o) {}
     @SuppressWarnings("unused")
-    @SkylarkCallable(doc = "")
+    @SkylarkCallable(documented = false)
     public void method(String i) {}
   }
 
@@ -1694,22 +1694,22 @@ public class SkylarkEvaluationTest extends EvaluationTest {
           Location.BUILTIN);
     }
 
-    @SkylarkCallable(name = "callable_only_field", doc = "", structField = true)
+    @SkylarkCallable(name = "callable_only_field", documented = false, structField = true)
     public String getCallableOnlyField() {
       return "fromSkylarkCallable";
     }
 
-    @SkylarkCallable(name = "callable_only_method", doc = "", structField = false)
+    @SkylarkCallable(name = "callable_only_method", documented = false, structField = false)
     public String getCallableOnlyMethod() {
       return "fromSkylarkCallable";
     }
 
-    @SkylarkCallable(name = "collision_field", doc = "", structField = true)
+    @SkylarkCallable(name = "collision_field", documented = false, structField = true)
     public String getCollisionField() {
       return "fromSkylarkCallable";
     }
 
-    @SkylarkCallable(name = "collision_method", doc = "", structField = false)
+    @SkylarkCallable(name = "collision_method", documented = false, structField = false)
     public String getCollisionMethod() {
       return "fromSkylarkCallable";
     }