--file docs

Author: cpsauer

refresh.template.py

@@ -3,8 +3,9 @@
 
 Interface (after template expansion):
 - `bazel run` to regenerate compile_commands.json, so autocomplete (and any other clang tooling!) reflect the latest Bazel build files.
-    - No arguments are needed; info from the rule baked into the template expansion.
+    - No arguments are needed; info from the rule is baked into the template expansion.
         - Any arguments passed are interpreted as arguments needed for the builds being analyzed.
+        - The one exception is --file=<file_target>, which can be used to update commands for just one file. This is intended for programmatic use from editor plugins.
     - Requires being run under Bazel so we can access the workspace root environment variable.
 - Output: a compile_commands.json in the workspace root that clang tooling (or you!) can look at to figure out how files are being compiled by Bazel
     - Crucially, this output is de-Bazeled; The result is a command that could be run from the workspace root directly, with no Bazel-specific requirements, environment variables, etc.

refresh_compile_commands.bzl

@@ -49,6 +49,8 @@ refresh_compile_commands(
         # exclude_headers = "external",
     # Still not fast enough?
         # Make sure you're specifying just the targets you care about by setting `targets`, above.
+    # That's still not enough; I'm working on a huge codebase!
+        # This tool supports a fast, incremental mode that can be used to add/update commands as individual files are opened. If you'd be willing to collaborate on writing a simple editor plugin invokes this editor on open, please write in! (And see --file flag in refresh.template.py)
 ```
 """