diff --git a/docs/tar.md b/docs/tar.md
index 6697b44..b43193e 100644
--- a/docs/tar.md
+++ b/docs/tar.md
@@ -1,16 +1,28 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-Wrapper to execute BSD tar
+General-purpose rule to create tar archives.
+
+Unlike [pkg_tar from rules_pkg](https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md#pkg_tar)
+this:
+
+- Does not depend on any Python interpreter setup
+- Does not have any custom program to produce the output, instead
+  we rely on a well-known C++ program called "tar".
+  Specifically, we use the BSD variant of tar since it provides a means
+  of controlling mtimes, uid, symlinks, etc.
+
+We also provide full control for tar'ring binaries including their runfiles.
+
 
 <a id="tar_rule"></a>
 
 ## tar_rule
 
 <pre>
-tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-mtree">mtree</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-srcs">srcs</a>)
+tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-compress">compress</a>, <a href="#tar_rule-mtree">mtree</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-srcs">srcs</a>)
 </pre>
 
-
+Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly.
 
 **ATTRIBUTES**
 
@@ -18,6 +30,7 @@
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="tar_rule-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="tar_rule-compress"></a>compress |  Compress the archive file with a supported algorithm.   | String | optional | "" |
 | <a id="tar_rule-mtree"></a>mtree |  An mtree specification file   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 | <a id="tar_rule-out"></a>out |  Resulting tar file to write   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional |  |
 | <a id="tar_rule-srcs"></a>srcs |  Files that are placed into the tar   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required |  |
@@ -28,9 +41,22 @@
 ## tar
 
 <pre>
-tar(<a href="#tar-name">name</a>, <a href="#tar-out">out</a>, <a href="#tar-kwargs">kwargs</a>)
+tar(<a href="#tar-name">name</a>, <a href="#tar-mtree">mtree</a>, <a href="#tar-kwargs">kwargs</a>)
 </pre>
 
+Wrapper macro around [`tar_rule`](#tar_rule).
+
+Allows the mtree to be supplied as an array literal of lines, in addition to a separate file, e.g.
+
+```
+mtree =[
+    "usr/bin uid=0 gid=0 mode=0755 type=dir",
+    "usr/bin/ls uid=0 gid=0 mode=0755 time=0 type=file content={}/a".format(package_name()),
+],
+```
+
+For the format of a line, see "There are four types of lines in a specification" on the man page for BSD mtree,
+https://man.freebsd.org/cgi/man.cgi?mtree(8)
 
 
 **PARAMETERS**
@@ -38,8 +64,8 @@
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="tar-name"></a>name |  <p align="center"> - </p>   |  none |
-| <a id="tar-out"></a>out |  <p align="center"> - </p>   |  <code>None</code> |
-| <a id="tar-kwargs"></a>kwargs |  <p align="center"> - </p>   |  none |
+| <a id="tar-name"></a>name |  name of resulting <code>tar_rule</code>   |  none |
+| <a id="tar-mtree"></a>mtree |  either an array of specification lines, or a label of a file that contains the lines.   |  <code>None</code> |
+| <a id="tar-kwargs"></a>kwargs |  additional named parameters to pass to <code>tar_rule</code>   |  none |
 
 
diff --git a/lib/BUILD.bazel b/lib/BUILD.bazel
index 64e8541..a1e177d 100644
--- a/lib/BUILD.bazel
+++ b/lib/BUILD.bazel
@@ -108,7 +108,11 @@
 bzl_library(
     name = "tar",
     srcs = ["tar.bzl"],
-    deps = ["//lib/private/docs:tar"],
+    deps = [
+        "//lib/private/docs:tar",
+        "@bazel_skylib//lib:types",
+        "@bazel_skylib//rules:write_file",
+    ],
 )
 
 bzl_library(
diff --git a/lib/tar.bzl b/lib/tar.bzl
index c807a40..ab3175a 100644
--- a/lib/tar.bzl
+++ b/lib/tar.bzl
@@ -1,18 +1,48 @@
-"Wrapper to execute BSD tar"
+"""General-purpose rule to create tar archives.
+
+Unlike [pkg_tar from rules_pkg](https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md#pkg_tar)
+this:
+
+- Does not depend on any Python interpreter setup
+- Does not have any custom program to produce the output, instead
+  we rely on a well-known C++ program called "tar".
+  Specifically, we use the BSD variant of tar since it provides a means
+  of controlling mtimes, uid, symlinks, etc.
+
+We also provide full control for tar'ring binaries including their runfiles.
+"""
 
 load("@bazel_skylib//lib:types.bzl", "types")
 load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("//lib/private:tar.bzl", _tar_lib = "tar_lib")
 
 tar_rule = rule(
+    doc = "Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly.",
     implementation = _tar_lib.implementation,
     attrs = _tar_lib.attrs,
     toolchains = ["@aspect_bazel_lib//lib:tar_toolchain_type"],
 )
 
-# FIXME: needs docs
-# buildifier: disable=function-docstring
 def tar(name, mtree = None, **kwargs):
+    """Wrapper macro around [`tar_rule`](#tar_rule).
+
+    Allows the mtree to be supplied as an array literal of lines, in addition to a separate file, e.g.
+
+    ```
+    mtree =[
+        "usr/bin uid=0 gid=0 mode=0755 type=dir",
+        "usr/bin/ls uid=0 gid=0 mode=0755 time=0 type=file content={}/a".format(package_name()),
+    ],
+    ```
+
+    For the format of a line, see "There are four types of lines in a specification" on the man page for BSD mtree,
+    https://man.freebsd.org/cgi/man.cgi?mtree(8)
+
+    Args:
+        name: name of resulting `tar_rule`
+        mtree: either an array of specification lines, or a label of a file that contains the lines.
+        **kwargs: additional named parameters to pass to `tar_rule`
+    """
     if types.is_list(mtree):
         write_target = "_{}.mtree".format(name)
         write_file(