From ba26e2bcf56103a04ffaba19214ce47df68d5164 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Thu, 20 Nov 2025 09:06:11 -0800
Subject: [PATCH] add more docs to AXL files

---
 format/format.axl | 15 ++++++++++++++-
 lint/lint.axl     | 23 ++++++++++++++++-------
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/format/format.axl b/format/format.axl
index 2f184126..d696d981 100644
--- a/format/format.axl
+++ b/format/format.axl
@@ -2,6 +2,19 @@
 
 Format builds a multi-formatter target and then runs it on the changed files.
 It's a simple example of interaction with version control, which Bazel only does via the workspace_status_command.
+
+Install:
+    Add rules_lint to MODULE.aspect.
+    See examples in https://github.com/bazel-starters
+
+Usage:
+    # Format changed files
+    aspect format
+    # Format all files
+    aspect format --all_files
+    # Specify the label of the format_multirun binary
+    aspect format --formatter_target=//path/to:formatter_bin
+    
 """
 
 def bazel_run(ctx: TaskContext, entrypoint: str, args: list[str]) -> std.process.Child:
@@ -100,6 +113,6 @@ format = task(
     implementation = impl,
     args = {
         "all_files": args.boolean(default = False),
-        "format_target": args.string(default = "//tools/format"),
+        "formatter_target": args.string(default = "//tools/format"),
     },
 )
diff --git a/lint/lint.axl b/lint/lint.axl
index 35c8a2ac..a93f5937 100644
--- a/lint/lint.axl
+++ b/lint/lint.axl
@@ -4,6 +4,18 @@ First, perform a build with linting aspects enabled, and selecting appropriate o
 These can be remotely cached like any other actions.
 
 Then collect the results for presentation, either locally on the terminal or in the code review with Aspect's Marvin bot.
+
+Install:
+    Add rules_lint to MODULE.aspect.
+    See examples in https://github.com/bazel-starters
+
+Usage:
+    # Lint all targets in the repository
+    aspect lint
+    # Lint specific targets
+    aspect lint -- //path/to:targets -//not:this_one
+    # Fix lint violations, where the underlying linter provides fixes
+    aspect lint --fix
 """
 
 # buildifier: disable=function-docstring
@@ -15,13 +27,10 @@ def impl(ctx: TaskContext) -> int:
     if ctx.args.fix:
         flags.append("--output_groups=rules_lint_patch")
         flags.append("--@aspect_rules_lint//lint:fix")
-    out = ctx.std.io.stdout
-    if out.is_tty:
-        flags.append("--output_groups=rules_lint_human")
-    else:
-        # Note: to test this codepath, run with:
-        # echo > nohup.out; nohup aspect-cli lint ; cat nohup.out
-        flags.append("--output_groups=rules_lint_machine")
+    # Note: to test the non-interactive codepath, run with:
+    # echo > nohup.out; nohup aspect lint ; cat nohup.out
+    flags.append("--output_groups=rules_lint_" + (
+        "human" if ctx.std.io.stdout.is_tty else "machine"))
     build = ctx.bazel.build(
         flags = flags,
         build_events = True,