docs: update readme and rule examples

README.md

@@ -30,9 +30,22 @@ diff(
 )
 ```
 
+### Compare binary files
+
+```starlark
+load("@diff.bzl//diff:defs.bzl", "cmp")
+
+cmp(
+    name = "compare_bins",
+    args = ["--bytes", "4", "--verbose"],
+    srcs = ["bin_a", "bin_b"],
+    out = "cmp_output"
+)
+```
+
 ### Keep generated sources up to date
 
-Pass `validate = 1` to `diff` to create a build validation error when a generated source input diverges from the output tree file.
+Pass `validate = 1` to `cmp` or `diff` to create a build validation error when a generated source input diverges from the output tree file.
 
 ```starlark
 load("@diff.bzl//diff:defs.bzl", "diff")
@@ -47,7 +60,7 @@ diff(
 )
 ```
 
-A build error message with command to run to patch the file will be output.
+An error message with command to run to patch the file will be output.
 
 ```
 ERROR: diff command exited with non-zero status.

diff/defs.bzl

@@ -7,6 +7,31 @@ load("//diff/private:diff.bzl", "diff_rule")
 def cmp(name, srcs, args = [], out = None, **kwargs):
     """Runs cmp (binary diff) between two files and returns the output.
 
+    Examples:
+
+    Compare two binaries.
+
+    ```starlark
+    cmp(
+        name = "compare_bins",
+        args = ["--bytes", "4", "--verbose"],
+        srcs = ["bin_a", "bin_b"],
+        out = "cmp_output"
+    )
+    ```
+
+    Run cmp in a genrule.
+
+    ```starlark
+    genrule(
+        name = "run_cmp",
+        srcs = ["bin_a", "bin_b"],
+        outs = ["cmp_output"],
+        cmd = "$(CMP_BIN) --verbose $(execpath bin_a) $(execpath bin_b) > $@",
+        toolchains = ["@diff.bzl//diff/toolchain:execution_type"],
+    )
+    ```
+
     Args:
         name: The name of the rule
         srcs: The files to compare.
@@ -54,6 +79,18 @@ def diff(name, srcs, args = ["--unified"], patch = None, **kwargs):
     )
     ```
 
+    Run diff in a genrule.
+
+    ```starlark
+    genrule(
+        name = "run_diff",
+        srcs = ["a.txt", "b.txt"],
+        outs = ["a.patch"],
+        cmd = "$(DIFF_BIN) --unified $(execpath a.txt) $(execpath b.txt) > $@",
+        toolchains = ["@diff.bzl//diff/toolchain:execution_type"],
+    )
+    ```
+
     _By default, diff creates a unified format patch by passing `["--unified"]`
     to `args`. If overriding arguments, --unified must be added explicitly._