Improve Bazel setup instructions (#861)

README.md

@@ -68,6 +68,8 @@ use_repo(use_extension("@periphery//bazel:generated.bzl", "generated"), "periphe
 bazel run @periphery -- scan --bazel
 ```
 
+This command queries your project to identify all top-level targets, generates an implementation of the [scan](https://github.com/peripheryapp/periphery/blob/master/bazel/rules.bzl) rule, and then invokes Bazel. You can filter the top-level targets with the `-—bazel-filter <value>` option, where `<value>` will be passed as the first argument to Bazel’s [filter](https://bazel.build/query/language#filter) operator. The generated query can be seen in the console with the `-—verbose` option.
+
 ## How To Use
 
 ### The `scan` Command

bazel/internal/scan/scan.bzl

@@ -26,7 +26,7 @@ def _force_indexstore_impl(settings, _attr):
         ],
     }
 
-_force_indexstore = transition(
+force_indexstore = transition(
     implementation = _force_indexstore_impl,
     inputs = [
         "//command_line_option:features",
@@ -138,7 +138,8 @@ def _scan_inputs_aspect_impl(target, ctx):
         ),
     ]
 
-def _scan_impl(ctx):
+# buildifier: disable=function-docstring
+def scan_impl(ctx):
     swift_srcs_set = sets.make()
     indexstores_set = sets.make()
     plists_set = sets.make()
@@ -203,30 +204,3 @@ scan_inputs_aspect = aspect(
     _scan_inputs_aspect_impl,
     attr_aspects = ["deps", "swift_target"],
 )
-
-scan = rule(
-    doc = "Scans the top-level deps and their transitive deps for unused code.",
-    attrs = {
-        "deps": attr.label_list(
-            cfg = _force_indexstore,
-            mandatory = True,
-            aspects = [scan_inputs_aspect],
-            doc = "Top-level project targets to scan.",
-        ),
-        "config": attr.string(doc = "Path to the periphery.yml configuration file."),
-        "periphery": attr.label(
-            doc = "The periphery executable target.",
-            default = "@periphery//:periphery",
-        ),
-        "_template": attr.label(
-            allow_single_file = True,
-            default = "@periphery//bazel/internal/scan:scan_template.sh",
-        ),
-    },
-    outputs = {
-        "project_config": "project_config.json",
-        "scan": "scan.sh",
-    },
-    implementation = _scan_impl,
-    executable = True,
-)

bazel/rules.bzl

@@ -2,9 +2,31 @@
     Periphery public rules.
 """
 
-load(
-    "//bazel/internal/scan:scan.bzl",
-    _scan = "scan",
-)
+load("//bazel/internal/scan:scan.bzl", "force_indexstore", "scan_impl", "scan_inputs_aspect")
 
-scan = _scan
+scan = rule(
+    doc = "Scans the top-level deps and their transitive deps for unused code.",
+    attrs = {
+        "deps": attr.label_list(
+            cfg = force_indexstore,
+            mandatory = True,
+            aspects = [scan_inputs_aspect],
+            doc = "Top-level project targets to scan.",
+        ),
+        "config": attr.string(doc = "Path to the periphery.yml configuration file."),
+        "periphery": attr.label(
+            doc = "The periphery executable target.",
+            default = "@periphery//:periphery",
+        ),
+        "_template": attr.label(
+            allow_single_file = True,
+            default = "@periphery//bazel/internal/scan:scan_template.sh",
+        ),
+    },
+    outputs = {
+        "project_config": "project_config.json",
+        "scan": "scan.sh",
+    },
+    implementation = scan_impl,
+    executable = True,
+)