Repository navigation
comments: cut multi-line # blocks, issue numbers and long docstrings to the one-line rule (part of #11215) #11249
Description
Comment audit at main 92b373be5, every top-level directory, .bzl, .bazel and .rs outside fixtures, testdata, third_party and patches. AGENTS.md: delete # inline comments by default, one line at most; docstrings are one short plain line; no issue numbers. #11127 adds a guard with an allowlist and converts nothing; this is the conversion.
Where
Counts (excluding # floor:, # gazelle:, # buildifier: and LCOV_EXCL lines):
- 99
#comment blocks of two or more lines in Starlark. By directory: core 23, tools 21, MODULE.bazel 9, ocaml 6, cc 4, capnproto 4, rust 4, haskell 3, flatbuffers 3, elixir 3, android 2, cli 2, cuda 2, erlang 2, swift 2, and one each in d, dart, env, lua, php, ruby, terraform, thrift. - 25 comments and doc comments with an issue number outside
MODULE.bazel, plus 17 non-floor comment lines inMODULE.bazel. - 100-plus Starlark function and module docstrings longer than three lines (
Args:blocks and rationale paragraphs).
Samples:
- Blocks:
core/quality/sources.bzl:88,:151;core/quality/support_tests.bzl:211;tools/workspace/BUILD.bazel:6;tools/testing/hermetic/defs.bzl:8,:85;cc/private/clang_syntax.bzl:272;cc/private/toolchains/BUILD.bazel:602,:612;rust/private/defs.bzl:515;rust/private/quality/tools/selene.BUILD.bazel:3;ocaml/private/toolchain/repos.bzl:101;haskell/private/toolchain/repos.bzl:309,:453;flatbuffers/private/codegen.bzl:32,:74;capnproto/private/codegen.bzl:38;elixir/private/toolchain/pins.bzl:19;MODULE.bazel:117,:234,:277. - Issue numbers:
cli/worktree/src/ops.rs:274,cli/output/src/lifecycle.rs:320,cli/adopt/src/preflight.rs:1,cli/cli/BUILD.bazel:184,cli/cli/src/exec/quality.rs:190,core/quality/curated_defaults.bzl:7,:150,core/quality/support_tests.bzl:227,core/quality/jvm_classpath_policy_test.rs:1,tools/testing/src/lib.rs:185,tools/testing/BUILD.bazel:233,tools/testing/floor/src/lib.rs:1,tools/docs/support_matrix/facts_tests.bzl:133,elixir/private/toolchain/pins.bzl:32,erlang/private/toolchain/pins.bzl:127,msix/tests/BUILD.bazel:547,MODULE.bazel:88,:92,:117. - Docstrings:
flatbuffers/private/conform.bzl:1(module docstring with rationale),core/conformance.bzl:260,gazelle/dispatch/hub.bzl:14,swift/private/toolchain/toolchain.bzl:81,tools/testing/nested_repository_cache.bzl:52,tools/docs/cc/defs.bzl,tools/docs/ocaml/defs.bzl,tools/docs/components/defs.bzl(4 each). - Multi-line
//blocks in Rust that restate history or other files:cli/cli/tests/agents/tests/dev_launcher.rs:16,cli/process/src/groups_tests.rs:236.
Fix
- Per directory, one PR: delete each multi-line
#block or cut it to one line that says what the code cannot (# Windows needs the runfiles tree.). - Delete
(#1234)andsee #1234from comments and doc comments. KeepLCOV_EXCLissue:fields and# floor:lines. - Cut each docstring to one line; drop
Args:blocks whose lines repeat the parameter name. - Shrink the guard: docs and comments carry no issue numbers or history, design pages stay under the word limit, every page is linted #11127 allowlist in the same PR when it has landed.
Done when
- No
.bzlor.bazelfile outside fixtures has two consecutive#comment lines other than directives. grep -rnE '(#|//).*\(#[0-9]{3,5}\)' --include=*.bzl --include=*.bazel --include=*.rsoutside fixtures prints only# floor:andLCOV_EXCLlines.
🤖 Generated with Claude Code
Activity
TrapsterDK commentedon Nov 11, 2026
Done in the PR for d, dart, lua, php, ruby, terraform, thrift blocks. Remaining: blocks in core, tools, MODULE.bazel, ocaml, cc, capnproto, rust, haskell, flatbuffers, elixir, android, cli, cuda, erlang, swift, env; issue numbers in comments; long docstrings; allowlist shrink.
comments: cut multi-line # blocks in d, dart, lua, php, ruby, terrafo…
comments: cut multi-line # blocks in d, dart, lua, php, ruby, terrafo…
TrapsterDK commentedon Nov 12, 2026
PR #12323 handles the multi-line blocks in ocaml, cc, capnproto, rust, haskell, flatbuffers, elixir, android, cuda, erlang and swift, removes issue numbers from code comments outside MODULE.bazel, and shrinks the allowlist. Still to do: multi-line blocks in core, tools, MODULE.bazel, cli and env; issue numbers in MODULE.bazel comments and in docs pages; long docstrings; multi-line
//blocks in Rust.comments: one-line # blocks in language dirs, drop issue numbers from…
comments: one-line # blocks in language dirs, drop issue numbers from…
TrapsterDK commentedon Nov 12, 2026
PR #12481 cuts the multi-line
#blocks in core, tools, cli and MODULE.bazel and drops issue numbers from non-floor MODULE.bazel comments. Still to do: issue numbers in docs pages; long Starlark docstrings; multi-line//blocks in Rust.comments: one-line # blocks in core, tools, cli and MODULE.bazel, dro…
comments: one-line # blocks in core, tools, cli and MODULE.bazel, dro…
TrapsterDK commentedon Nov 13, 2026
PR for Rust // blocks done except ~38 that do not fit one line. Remaining: issue numbers in docs/support-matrix.md and docs/design/layout.md; long Starlark docstrings; remaining long Rust // blocks.
comments: one-line // blocks in Rust sources (part of #11249) (#12620)
TrapsterDK commentedon Nov 13, 2026
Rust // blocks done except the two generated-file headers. Remaining: long Starlark docstrings.
comments: cut remaining multi-line Rust // blocks to one line (part of …
19 remaining items
TrapsterDK commentedon Nov 14, 2026
PR #12709 covers deploy/ and cli/ .bzl docstrings and # comments. Remaining: other directories' .bzl docstrings and top-level # blocks.
TrapsterDK commentedon Nov 14, 2026
Slice zig/sql/haskell/flatbuffers indented comments and docstrings done in a PR. Remaining: other directories' docstrings and comments.
comments: shorten deploy and cli .bzl docstrings, delete # comments (…
comments: delete indented # comments in cc, elixir, erlang, ocaml, ca…
TrapsterDK commentedon Nov 14, 2026
PR #12712 covers tools/ .bzl (not conformance) docstrings and # comments. Remaining: other directories' .bzl docstrings and comments.
comments: delete indented # comments and shorten docstrings in haskel…
comments: one-line docstrings and no # comments in tools .bzl (part of …
TrapsterDK commentedon Nov 14, 2026
PR #12718 covers remaining indented # comments and multi-line docstrings in gazelle, javascript, julia, ruby, terraform, thrift, typescript, cuda, dart, env, lua, php .bzl. Remaining: any top-level # blocks outside covered dirs.
comments: one-line docstrings and no # comments in remaining .bzl (pa…
TrapsterDK commentedon Nov 14, 2026
PR #12731 covers haskell .bzl docstrings/comments; go, swift, apple already clean. Remaining: other directories' .bzl docstrings and comments.
docs: one-line docstrings and no comments in haskell .bzl (part of #1…
comments: one-line docstrings in python, tools, cc, core, ocaml .bzl …
TrapsterDK commentedon Nov 14, 2026
PR #12736 shortens the last seven multi-line .bzl docstrings on main. Remaining: none found; leftover multi-line # blocks are license headers and
# keepdirectives.TrapsterDK commentedon Nov 14, 2026
Done: the last slice merged in #12736 and a scan finds nothing left.
🤖 Generated with Claude Code