starlark: fix docs and wrapper signature tests (closes #9752)

deploy/rules/archive.bzl

@@ -449,10 +449,7 @@ _consumer_tarball = rule(
 )
 
 def consumer_archive(name, app, min_runtime, linkage = "dynamic", resources = [], runtime = [], notice = None, license_file = None, check_imports = True, format = "tar.gz", platform = None, tags = None, target_compatible_with = None, visibility = None, testonly = None):
-    """Packages one consumer app with runtime, resources, NOTICE and IDENTITY as a tar.gz or zip and sha256 file.
-
-    `name` is the archive; `name_checksum` is its sha256 file. `name_stage` and `name_archive` are helpers.
-    """
+    """Packages one consumer app with runtime, resources, NOTICE and IDENTITY as a tar.gz or zip and sha256 file. `name` is the archive; `name_checksum` is its sha256 file. `name_stage` and `name_archive` are helpers."""
     (tarball, checksum) = archive_filenames(name, format)
     stage_target = name + "_stage"
     archive_target = name + "_archive"

deploy/rules/config.bzl

@@ -40,10 +40,7 @@ def deploy_config(ctx, kind, values, runfiles):
     ]
 
 def deploy_identity(name, package, version, name_error, version_error):
-    """Returns the (package, version) a deploy macro publishes.
-
-    The package defaults to the target name. An empty version means the launcher reads it from the manifest.
-    """
+    """Returns the (package, version) a deploy macro publishes. The package defaults to the target name. An empty version means the launcher reads it from the manifest."""
     pkg = package or name
     where = " (in " + native.package_name() + ":" + name + ")"
     error = name_error(pkg)

deploy/rules/crates.bzl

@@ -69,12 +69,7 @@ _crates_config = rule(
 )
 
 def crates_deploy(name, crate, package = "", version = "", build_mode = "release", api_compat = "fail", api_baseline = "registry", sbom = None, size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes staged crate sources as a local-first crates.io deployment.
-
-    api_compat and api_baseline work as described under "Public API
-    compatibility" in the README; the tool is cargo-semver-checks, and the
-    git baseline needs a checked-in, standalone Cargo.toml.
-    """
+    """Publishes staged crate sources as a local-first crates.io deployment. api_compat and api_baseline work as described under "Public API compatibility" in the README; the tool is cargo-semver-checks, and the git baseline needs a checked-in, standalone Cargo.toml."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     pkg, version = deploy_identity(name, package, version, crates_name_error, crates_version_error)
 

deploy/rules/github.bzl

@@ -114,17 +114,7 @@ github_config = rule(
 )
 
 def github_deploy(name, artifacts, release_tag = "", tag_from_head = False, build_mode = "release", sbom = None, notes = "commits", notes_file = None, api_compat = "fail", api_baseline = "registry", go_modules = [], size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes pinned files as a draft-only GitHub Release.
-
-    `sbom` is a dx_sbom target uploaded as one more release asset.
-    `release_tag` defaults to "v0.0.0-dryrun"; `tag_from_head = True` uses the
-    tag that points at HEAD instead.
-    `notes` is "commits" (the grouped commit list since the previous tag) or
-    "none"; `notes_file` is a markdown file used as the release body instead.
-    `api_compat` and `api_baseline` work as described under "Public API
-    compatibility" in the README; the tool is apidiff on each of `go_modules`
-    (workspace-relative directories; empty means the go.mod at the root).
-    """
+    """Publishes pinned files as a draft-only GitHub Release. `sbom` is a dx_sbom target uploaded as one more release asset. `release_tag` defaults to "v0.0.0-dryrun"; `tag_from_head = True` uses the tag that points at HEAD instead. `notes` is "commits" (the grouped commit list since the previous tag) or "none"; `notes_file` is a markdown file used as the release body instead. `api_compat` and `api_baseline` work as described under "Public API compatibility" in the README; the tool is apidiff on each of `go_modules` (workspace-relative directories; empty means the go.mod at the root)."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     if tag_from_head:
         if release_tag != "":

deploy/rules/maven.bzl

@@ -116,11 +116,7 @@ _maven_config = rule(
 )
 
 def maven_deploy(name, jar, pom, group, artifact = "", version = "", build_mode = "release", sources = None, javadoc = None, sbom = None, api_compat = "fail", api_baseline = "registry", size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes one jar plus its pom, and optional sources and javadoc jars, as a local-first Maven deployment.
-
-    api_compat and api_baseline work as described under "Public API
-    compatibility" in the README; the tool is japicmp on the jar.
-    """
+    """Publishes one jar plus its pom, and optional sources and javadoc jars, as a local-first Maven deployment. api_compat and api_baseline work as described under "Public API compatibility" in the README; the tool is japicmp on the jar."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     group_error = maven_group_error(group)
     if group_error != "":

deploy/rules/native_probe.bzl

@@ -32,6 +32,6 @@ native_probe_runtime_files = rule(
     implementation = _runtime_files_impl,
     doc = "Copies the files of a native_runtime next to the probe package so a wheel ships them.",
     attrs = {
-        "runtime": attr.label(mandatory = True, providers = [NativeRuntimeInfo]),
+        "runtime": attr.label(mandatory = True, providers = [NativeRuntimeInfo], doc = "The native_runtime whose files are copied."),
     },
 )

deploy/rules/npm.bzl

@@ -48,11 +48,7 @@ _npm_config = rule(
 )
 
 def npm_deploy(name, package = "", dist_tag = "latest", srcs = [], registry_url = "https://registry.npmjs.org", access = "public", provenance = "", build_mode = "release", sbom = None, api_compat = "fail", api_baseline = "registry", size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Packs files into a local npm feed with public or restricted access and a provenance policy.
-
-    api_compat and api_baseline work as described under "Public API
-    compatibility" in the README; the tool is api-extractor on the types entry.
-    """
+    """Packs files into a local npm feed with public or restricted access and a provenance policy. api_compat and api_baseline work as described under "Public API compatibility" in the README; the tool is api-extractor on the types entry."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     package, _ = deploy_identity(name, package, "", npm_package_error, npm_package_error)
     tag_error = npm_tag_error(dist_tag)

deploy/rules/nuget.bzl

@@ -113,11 +113,7 @@ _nuget_config = rule(
 )
 
 def nuget_deploy(name, nupkg, package = "", version = "", registry_url = NUGET_DEFAULT_REGISTRY_URL, build_mode = "release", sbom = None, api_compat = "fail", api_baseline = "registry", size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes one nupkg after checking its nuspec id and version.
-
-    api_compat and api_baseline work as described under "Public API
-    compatibility" in the README; the tool is Microsoft.DotNet.ApiCompat.
-    """
+    """Publishes one nupkg after checking its nuspec id and version. api_compat and api_baseline work as described under "Public API compatibility" in the README; the tool is Microsoft.DotNet.ApiCompat."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     pkg, version = deploy_identity(name, package, version, nuget_id_error, nuget_version_error)
     api_error = api_compat_error("nuget_deploy", api_compat, api_baseline)

deploy/rules/octopus.bzl

@@ -166,10 +166,7 @@ _octopus_config = rule(
 )
 
 def octopus_deploy(name, srcs, project, package = "", channel = "Default", version = "", deploy_to = [], space = "", registry_url = OCTOPUS_DEFAULT_REGISTRY_URL, build_mode = "release", sbom = None, size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes one `<package>.<version>.tar.gz` archive as a local-first Octopus deployment.
-
-    The package id defaults to the target name. An empty version means the launcher reads it from the archive filename.
-    """
+    """Publishes one `<package>.<version>.tar.gz` archive as a local-first Octopus deployment. The package id defaults to the target name. An empty version means the launcher reads it from the archive filename."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     project_error = octopus_project_error(project)
     if project_error != "":

deploy/rules/pypi.bzl

@@ -125,13 +125,7 @@ _pypi_config = rule(
 )
 
 def pypi_deploy(name, wheel, sdist = None, registry_url = PYPI_DEFAULT_REGISTRY_URL, build_mode = "release", sbom = None, api_compat = "fail", api_baseline = "registry", api_package = "", api_src = "", size_budget = "", tags = [], visibility = None, testonly = False, target_compatible_with = []):
-    """Publishes one wheel plus an optional sdist as a local-first PyPI deployment.
-
-    api_compat and api_baseline work as described under "Public API
-    compatibility" in the README; the tool is griffe. api_package is the import
-    name, which defaults to the distribution name, and api_src the
-    workspace-relative source directory the git baseline needs.
-    """
+    """Publishes one wheel plus an optional sdist as a local-first PyPI deployment. api_compat and api_baseline work as described under "Public API compatibility" in the README; the tool is griffe. api_package is the import name, which defaults to the distribution name, and api_src the workspace-relative source directory the git baseline needs."""
     attrs = deploy_attrs(tags, visibility, testonly, target_compatible_with)
     name_error = pypi_name_error(name)
     if name_error != "":

families/dotnet/fsharp/rules/defs.bzl

@@ -92,7 +92,7 @@ def fsharp_test(name, *, srcs = None, visibility = None, **kwargs):
         fail("fsharp_test //" + native.package_name() + ":" + name + " needs srcs")
     dx_wrap_test(name, _fsharp_test, _fsharp_forward_test, srcs, visibility = visibility, upstream_kwargs = fsharp_tfm_with_defaults(kwargs), extra_forward_kwargs = _fsharp_context(kwargs), coverage_collector = FSHARP_COVERAGE_COLLECTOR, **kwargs)
 
-def fsharp_bench(name, srcs, deps = None, tags = None, **kwargs):
+def fsharp_bench(name, *, srcs, deps = None, tags = None, **kwargs):
     """An fsharp_test that runs the [<Benchmark>] classes in srcs with BenchmarkDotNet and writes dx-bench.json."""
     fsharp_test(
         name = name,

generation/codegen.bzl

@@ -43,19 +43,7 @@ DX_CODEGEN_PLAN_OUTPUT_GROUP = "dx_codegen_plans"
 CODEGEN_RUST_EDITION = "2021"
 
 def codegen_rust_library_kwargs(name, generated, crate_name, runtime, deps, kwargs):
-    """Arguments of the rust_library wrapping a generated crate.
-
-    Args:
-      name: Name of the rust_library.
-      generated: Label of the target generating the crate sources.
-      crate_name: Crate name, or None for name.
-      runtime: Labels of the runtime crates.
-      deps: Dependencies of the caller, added after the runtime.
-      kwargs: Caller arguments; they override the defaults, and srcs and deps are added to.
-
-    Returns:
-      Keyword arguments for rust_library.
-    """
+    """Arguments of the rust_library wrapping a generated crate."""
     args = {
         "crate_name": (crate_name or name).replace("-", "_"),
         "crate_root": None,

java/rules/defs.bzl

@@ -110,13 +110,5 @@ def java_fuzz_test(name, srcs = None, target_class = None, visibility = None, ta
     jazzer_fuzz(name, java_library, srcs, deps, target_class, visibility, tags, kwargs)
 
 def java_bench(name, srcs, deps = [], tags = [], **kwargs):
-    """Runs the JMH benchmarks in srcs and writes dx-bench.json for dx bench.
-
-    Args:
-      name: the test target.
-      srcs: Java sources with @Benchmark methods.
-      deps: libraries the benchmarks use.
-      tags: extra tags. dx-bench and manual are added.
-      **kwargs: passed to the test.
-    """
+    """Runs the JMH benchmarks in srcs and writes dx-bench.json for dx bench."""
     jmh_bench(name, java_library, java_jmh_test, srcs, deps, tags, kwargs)

java/rules/jmh.bzl

@@ -64,19 +64,17 @@ def _jmh_generated_impl(ctx):
 
 _jmh_generated = rule(
     implementation = _jmh_generated_impl,
+    doc = "Runs the JMH bytecode generator over a library jar into a source jar and resources.",
     attrs = {
-        "lib": attr.label(providers = [JavaInfo], mandatory = True),
-        "srcjar": attr.output(mandatory = True),
-        "resources": attr.output(mandatory = True),
+        "lib": attr.label(providers = [JavaInfo], mandatory = True, doc = "The compiled benchmark library."),
+        "srcjar": attr.output(mandatory = True, doc = "The generated Java sources."),
+        "resources": attr.output(mandatory = True, doc = "The generated JMH resources."),
         "_generator": attr.label(default = _GENERATOR, executable = True, cfg = "exec"),
     },
 )
 
 def jmh_bench_generated(name, library, test, srcs, deps, tags, kwargs, library_kwargs = {}):
-    """Like jmh_bench for languages whose compiler runs no Java annotation processors.
-
-    The library compiles without the processor, JmhGenerate runs the JMH bytecode generator over its jar, and javac compiles the generated Java.
-    """
+    """Like jmh_bench for languages whose compiler runs no Java annotation processors. The library compiles without the processor, JmhGenerate runs the JMH bytecode generator over its jar, and javac compiles the generated Java."""
     library(
         name = name + "_bin",
         srcs = srcs,

javascript/rules/frameworks.bzl

@@ -94,12 +94,7 @@ def _dx_framework_vite_run(name, out, srcs, config, node_modules, packages, mnem
     )
 
 def dx_framework_build(name, what, mnemonic, packages, srcs, config, node_modules, package_json = None, public = None, ssr_entry = None, deps = None, visibility = None, tool = _VITE_TOOL, keep_entry_path = False, **kwargs):
-    """Builds one framework app into a bundled web app tree and an optional SSR tree.
-
-    Creates the private `<name>_dist` build target behind the web app `<name>`.
-    With `ssr_entry` it also creates `<name>_ssr`, which takes the given visibility.
-    `tags`, `testonly` and `target_compatible_with` reach every target.
-    """
+    """Builds one framework app into a bundled web app tree and an optional SSR tree. Creates the private `<name>_dist` build target behind the web app `<name>`. With `ssr_entry` it also creates `<name>_ssr`, which takes the given visibility. `tags`, `testonly` and `target_compatible_with` reach every target."""
     tags = kwargs.get("tags", [])
     testonly = kwargs.get("testonly", False)
     compatible = kwargs.get("target_compatible_with", None)

kotlin/rules/defs.bzl

@@ -131,15 +131,7 @@ def kotlin_test(name, srcs = None, visibility = None, **kwargs):
     )
 
 def kotlin_bench(name, srcs, deps = [], tags = [], **kwargs):
-    """Runs the JMH benchmarks in Kotlin srcs and writes dx-bench.json for dx bench.
-
-    Args:
-      name: the test target.
-      srcs: Kotlin sources with @Benchmark methods.
-      deps: libraries the benchmarks use.
-      tags: extra tags. dx-bench and manual are added.
-      **kwargs: passed to the test.
-    """
+    """Runs the JMH benchmarks in Kotlin srcs and writes dx-bench.json for dx bench."""
     kt_javac_options(
         name = name + "_javac_opts",
         warn = "off",
@@ -149,17 +141,7 @@ def kotlin_bench(name, srcs, deps = [], tags = [], **kwargs):
     jmh_bench(name, kotlin_library, java_jmh_test, srcs, deps, tags, kwargs, {"javac_opts": ":" + name + "_javac_opts"})
 
 def kotlin_fuzz_test(name, srcs, target_class, deps = None, visibility = None, tags = None, **kwargs):
-    """A Jazzer fuzz target plus a `<name>_run` runner for `dx fuzz`.
-
-    Args:
-      name: the fuzz binary; the runner is `<name>_run`.
-      srcs: Kotlin sources. The target class needs a static `fuzzerTestOneInput`, so use `@JvmStatic` in an object.
-      target_class: the class Jazzer fuzzes.
-      deps: libraries the target uses.
-      visibility: visibility of the binary and the runner.
-      tags: extra tags. dx-fuzz and manual are added.
-      **kwargs: `args` and `target_compatible_with` go to the binary, the rest to the library.
-    """
+    """A Jazzer fuzz target plus a `<name>_run` runner for `dx fuzz`."""
     kt_javac_options(
         name = name + "_javac_opts",
         warn = "off",

libs/starlark/fuzz.bzl

@@ -33,16 +33,7 @@ dx_fuzz_binary = rule(
 )
 
 def dx_fuzz_runner(name, fuzz, engine = "libfuzzer", target = "", harness = None, visibility = None):
-    """Defines `<name>_run`, the runner `dx fuzz` calls for the fuzz binary `fuzz`.
-
-    Args:
-      name: the fuzz target; the runner is `<name>_run`.
-      fuzz: label of the fuzz binary or test.
-      engine: `libfuzzer`, `jazzer`, `go` or `dotnet`.
-      target: the Jazzer target class or the Go fuzz function; unused for libfuzzer and dotnet.
-      harness: label of the .NET harness the `dotnet` engine passes to `fuzz` as `--target_path`.
-      visibility: visibility of the runner.
-    """
+    """Defines `<name>_run`, the runner `dx fuzz` calls for the fuzz binary `fuzz`."""
     sh_binary(
         name = name + "_run",
         srcs = [Label("//libs/starlark:fuzz_run.sh")],

ocaml/toolchain/opam.bzl

@@ -87,10 +87,7 @@ def _locked_version(filt):
     return version
 
 def parse_depends(text):
-    """Returns {package: version} for the depends entries that pin a version.
-
-    Entries limited to tests, docs or development versions are left out.
-    """
+    """Returns {package: version} for the depends entries that pin a version. Entries limited to tests, docs or development versions are left out."""
     at = _field(text, "depends:")
     if at < 0:
         return {}
@@ -131,11 +128,7 @@ def _hex_to_base64(digits):
     return out
 
 def parse_url(text):
-    """Returns struct(src, sha256, integrity) from the `url` section of an opam file.
-
-    A file with only a sha512 checksum gets an empty sha256 and a
-    `sha512-<base64>` integrity.
-    """
+    """Returns struct(src, sha256, integrity) from the `url` section of an opam file. A file with only a sha512 checksum gets an empty sha256 and a `sha512-<base64>` integrity."""
     at = _field(text, "url")
     if at < 0:
         fail("the opam file has no url section")

python/rules/defs.bzl

@@ -212,9 +212,10 @@ def _srcs_impl(ctx):
 
 _py_grpc_srcs = rule(
     implementation = _srcs_impl,
+    doc = "Compiles the gRPC services of a proto_library into Python stubs.",
     attrs = {
-        "proto": attr.label(mandatory = True, providers = [ProtoInfo]),
-        "tool": attr.label(mandatory = True, executable = True, cfg = "exec"),
+        "proto": attr.label(mandatory = True, providers = [ProtoInfo], doc = "The proto_library with the service."),
+        "tool": attr.label(mandatory = True, executable = True, cfg = "exec", doc = "The protoc binary from grpcio-tools."),
         "_exec_os": attr.label(
             default = "//libs/exec_os",
             cfg = "exec",
@@ -224,17 +225,7 @@ _py_grpc_srcs = rule(
 )
 
 def python_grpc_library(name, proto, py_proto, grpc_tools = "@pypi//grpcio_tools", grpc = "@pypi//grpcio", dep_group = None, **kwargs):
-    """Compiles the services of proto into <name>_pb2_grpc.py.
-
-    Args:
-      name: target name of the py_library.
-      proto: the proto_library with the service. It must sit in the same package.
-      py_proto: the py_proto_library for the same proto_library.
-      grpc_tools: label of the grpcio-tools package that provides protoc.
-      grpc: label of the grpcio package the stubs import.
-      dep_group: uv project name for the packages, when the hub has several.
-      **kwargs: forwarded to the py_library, for example visibility.
-    """
+    """Compiles the services of proto into <name>_pb2_grpc.py."""
     python_binary(
         name = name + "_protoc",
         srcs = ["@rules_dx//python/rules:grpc_protoc.py"],