Repository: bazelbuild/bazel
Issue: `repository_rule` should have a `doc` argument
Labels: type: feature request
P2
team-ExternalDeps

`repository_rule` is similar to `rule`, except it lives on the `WORKSPACE` level. `rule` has a nice `doc` attribute which is extracted by documentation tools. It would be nice if `repository_rule` followed suit.

In [`rules_nixpkgs`](https://github.com/tweag/rules_nixpkgs) and [`rules_haskell`](https://github.com/tweag/rules_haskell) we have to resort to [manually written docs](https://github.com/tweag/rules_nixpkgs/blob/master/README.md#rules-1), which tend go out of sync easily.

Issue comments:
Sounds like a great idea!
Just hit this too. It looks like the fix is trivial (adding a no-op `doc` parameter), so I've mailed https://github.com/bazelbuild/bazel/pull/6936 . Note that rules using this param won't work with any older Bazel versions.

Pull request review comments:

Patch that resolved the issue:
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
index 31846125fc0e6b..d68fff2a12eac6 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
@@ -61,7 +61,8 @@ public BaseFunction repositoryRule(
       Boolean local,
       SkylarkList<String> environ,
       FuncallExpression ast,
-      com.google.devtools.build.lib.syntax.Environment funcallEnv)
+      com.google.devtools.build.lib.syntax.Environment funcallEnv,
+      String doc)
       throws EvalException {
     SkylarkUtils.checkLoadingOrWorkspacePhase(funcallEnv, "repository_rule", ast.getLocation());
     // We'll set the name later, pass the empty string for now.
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryModuleApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryModuleApi.java
index 36728cb4856864..fdc5e9313e7278 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryModuleApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryModuleApi.java
@@ -78,6 +78,15 @@ public interface RepositoryModuleApi {
                     + "an environment variable in that list change, the repository will be "
                     + "refetched.",
             named = true,
+            positional = false),
+        @Param(
+            name = "doc",
+            type = String.class,
+            defaultValue = "''",
+            doc =
+                "A description of the repository rule that can be extracted by documentation "
+                    + "generating tools."
+            named = true,
             positional = false)
       },
       useAst = true,
@@ -88,6 +97,7 @@ public BaseFunction repositoryRule(
       Boolean local,
       SkylarkList<String> environ,
       FuncallExpression ast,
-      Environment env)
+      Environment env,
+      String doc)
       throws EvalException;
 }
diff --git a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java
index 8f22cb7585ca11..abee2f3b8f9f23 100644
--- a/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java
+++ b/src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository/FakeRepositoryModule.java
@@ -27,7 +27,7 @@ public class FakeRepositoryModule implements RepositoryModuleApi {
 
   @Override
   public BaseFunction repositoryRule(BaseFunction implementation, Object attrs, Boolean local,
-      SkylarkList<String> environ, FuncallExpression ast, Environment env) {
+      SkylarkList<String> environ, FuncallExpression ast, Environment env, String doc) {
     return implementation;
   }
 }


Test patch:
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
index d083028376cf84..24a75a703bd7d2 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/input.bzl
@@ -8,7 +8,10 @@ def my_rule_impl(ctx):
 def exercise_the_api():
     var1 = config_common.FeatureFlagInfo
     var2 = platform_common.TemplateVariableInfo
-    var3 = repository_rule(implementation = my_rule_impl)
+    var3 = repository_rule(
+        implementation = my_rule_impl,
+        doc = "This repository rule has documentation.",
+    )
     var4 = testing.ExecutionInfo({})
 
 exercise_the_api()