docs(jq): document empty srcs

bazel-contrib · Apr 19, 2023 · a04c312 · a04c312
1 parent e9c0612
commit a04c312
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 8 deletions.
diff --git a/docs/jq.md b/docs/jq.md
diff --git a/docs/stamping.md b/docs/stamping.md
diff --git a/lib/jq.bzl b/lib/jq.bzl
@@ -26,14 +26,23 @@ def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, **k
  ```starlark
  load("@aspect_bazel_lib//lib:jq.bzl", "jq")
 
- # Remove fields from package.json
+ # Create a new file bazel-out/.../no_srcs.json
+ jq(
+ name = "no_srcs",
+ srcs = [],
+ filter = ".name = \"Alice\"",
+ )
+
+ # Remove fields from package.json.
+ # Writes to bazel-out/.../package.json which means you must refer to this as ":no_dev_deps"
+ # since Bazel doesn't allow a label for the output file that collides with the input file.
  jq(
  name = "no_dev_deps",
  srcs = ["package.json"],
  filter = "del(.devDependencies)",
  )
 
- # Merge bar.json on top of foo.json
+ # Merge bar.json on top of foo.json, producing foobar.json
  jq(
  name = "merged",
  srcs = ["foo.json", "bar.json"],
@@ -102,7 +111,7 @@ def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, **k
 
  Args:
  name: Name of the rule
- srcs: List of input files
+ srcs: List of input files. May be empty.
  filter: Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters).
  Subject to stamp variable replacements, see [Stamping](./stamping.md).
  When stamping is enabled, a variable named "STAMP" will be available in the filter.