Improve documentation for string parameter macros

- Split the section out of `build_rule.md` for accessibility
- Add documentation for missing macro types
- Add examples
- Fix misleading statement in `cheatsheet.md`

docs/concepts/build_rule.md

@@ -130,37 +130,6 @@ editing its source code.
 ## String parameter macros
 
 It is also possible to expand references to other rules within the `cmd`, using
-builtin `string parameter macros`. All build rules expanded in the command are
-automatically considered to be dependencies of the `genrule()`.
-
-Note that the paths returned by these macros are _relative_ paths. Using
-relative paths ensures that your builds are _hermetic_, that is, they are
-reproducible across different machine environments.
-
-`$(classpath //path/to:target)`
-
-Expands to the transitive classpath of the specified build rule, provided that
-the rule has a Java classpath. If the rule does not have (or contribute to) a
-classpath, then an exception is thrown and the build breaks.
-
-`$(exe //path/to:target)`
-
-Expands a build rule that results in an executable to the commands necessary to
-run that executable. For example, a `java_binary()` might expand to a call to
-`java -jar path/to/target.jar` . Files that are executable (perhaps generated by
-a `genrule()`) are also expanded. If the build rule does not generate an
-executable output, then an exception is thrown and the build breaks.
-
-If the `$(exe my_dependency)` dependency should actually be built with the
-target platform, use `$(exe_target my_dependency)` instead, which will stick to
-the same platform as the target.
-
-`$(location //path/to:target)`
-
-Expands to the location of the output of the specified build rule. This means
-that you can refer to the output without needing to be aware of how Buck is
-storing data on the disk mid-build.
-
-```
-
-```
+the builtin [`string parameter macros`](string_parameter_macros.md). All build
+rules expanded in the command are automatically considered to be dependencies of
+the `genrule()`.

docs/concepts/string_parameter_macros.md

@@ -0,0 +1,144 @@
+---
+id: string_parameter_macros
+title: String parameter macros
+---
+
+# String parameter macros
+
+Many rule attributes (the ones with type `attrs.arg`) support expanding
+references to other rules using a mechanism called string parameter macros. All
+expanded build rules are automatically added as dependencies.
+
+Note that the paths returned by these macros are _relative_ paths. Using
+relative paths ensures that your builds are _hermetic_, that is, they are
+reproducible across different machine environments.
+
+## `$(location //path/to:target)`
+
+Expands to the location of the output of the specified build rule. This means
+that you can refer to the output without needing to be aware of how Buck is
+storing data on the disk mid-build.
+
+For example:
+
+```starlark
+cxx_test(
+    name = "my_test",
+    srcs = ["main.cpp"],
+    preprocessor_flags = ["-DTEST_DIR=$(location :test_dir)"],
+)
+
+filegroup(
+    name = "test_dir",
+    srcs = [
+        "test_files/foo.json",
+        "test_files/bar.toml",
+    ],
+)
+```
+
+## `$(source relative/path/to/source)`
+
+Expands to the location of the specified source. The difference with using
+`$(location path/to:export_file_target)` is that the path points to the file in
+the source tree, rather than a copy or symlink in `buck-out`.
+
+For example:
+
+```starlark
+cxx_test(
+    name = "my_test",
+    srcs = ["main.cpp"],
+    preprocessor_flags = ["-DMY_SOURCE_FILE=$(source path/to/my_source_file)"],
+)
+```
+
+## `$(exe //path/to:target)`
+
+Expands a build rule that results in an executable to the commands necessary to
+run that executable as part of the build.
+
+For example, a `java_binary()` might expand to a call to `java -jar
+path/to/target.jar`. Files that are executable (perhaps generated by a
+`genrule()`) are also expanded.
+
+If the build rule does not generate an executable output, then an exception is
+thrown and the build breaks.
+
+If the `$(exe my_dependency)` dependency should actually be built with the
+target platform, use `$(exe_target my_dependency)` instead, which will stick to
+the same platform as the target.
+
+## `$(exe_target //path/to:target)`
+
+Identical to `$(exe //path/to:target)`, except that the target is built using
+the target platform, rather than the execution platform.
+
+This is for example useful to get the paths to executables to be run as part of
+tests. For example:
+
+```starlark
+sh_test(
+    name = "my_test",
+    args = [
+        "$(exe_target //path/to:target_to_test)",
+    ],
+    # `my_test.sh` takes a single argument, which is the path to an executable
+    # to test.
+    test = "my_test.sh",
+    visibility = ["//risk/tap_enricher/..."],
+)
+```
+
+## `$(query_targets queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with the matching
+targets.
+
+For example:
+
+```starlark
+my_rule(
+    name = "example",
+    # Will be replaced by all dependencies of `some_target`.
+    foo = "$(query_targets deps(:some_target))"
+)
+```
+
+## `$(query_outputs queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with the outputs of the
+matching targets.
+
+For example:
+
+```starlark
+my_rule(
+    name = "example",
+    # Will be replaced by the outputs of all dependencies of `some_target`.
+    foo = "$(query_outputs deps(:some_target))"
+)
+```
+
+## `$(query_targets_and_outputs [separator] queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with matching targets
+and their outputs, which are separated by an optional `separator` (defaults to a
+space).
+
+For example:
+
+```starlark
+my_rule(
+    name = "example",
+    # Will be replaced by the space-separated dependencies of `some_target`, as
+    # well as their outputs.
+    foo = "$(query_targets_and_outputs deps(:some_target))"
+)
+```
+
+## `$(classpath //path/to:target)`
+
+Expands to the transitive classpath of the specified build rule, provided that
+the rule has a Java classpath. If the rule does not have (or contribute to) a
+classpath, then an exception is thrown and the build breaks.

docs/users/cheatsheet.md

@@ -84,7 +84,8 @@ $(query_outputs "queryfunction(//:foo)")
 $(query_targets_and_outputs [SEPARATOR] "queryfunction(//:foo)")
 ```
 
-Note, however, that the query macros are supported only for
+Note, however, that the query macros are supported only for rule
+attributes of type `attrs.arg`, such as
 [`genrule`](../../prelude/globals/#genrule) and
 [`apk_genrule`](../../prelude/globals/#apk_genrule).