diff --git a/pkgs/build-support/compress-drv/default.nix b/pkgs/build-support/compress-drv/default.nix
index f5507cb3d3ed..1eefe2bd373e 100644
--- a/pkgs/build-support/compress-drv/default.nix
+++ b/pkgs/build-support/compress-drv/default.nix
@@ -4,36 +4,51 @@
   runCommand,
 }:
 /**
-  #  compressDrv compresses files in a given derivation.
+  Compresses files of a given derivation, and returns a new derivation with
+  compressed files
 
-  ## Inputs:
+  # Inputs
 
   `formats` ([String])
 
   : List of file extensions to compress. Example: `["txt" "svg" "xml"]`.
 
-  `compressors` (String -> String)
+  `compressors` ( { ${fileExtension} :: String })
 
   : Map a desired extension (e.g. `gz`) to a compress program.
 
-  The compressor program that will be executed to get the `COMPRESSOR` extension.
-  The program should have a single " {}", which will be the replaced with the
-  target filename.
+    The compressor program that will be executed to get the `COMPRESSOR` extension.
+    The program should have a single " {}", which will be the replaced with the
+    target filename.
 
-  Compressor must:
-  - read symlinks (thus --force is needed to gzip, zstd, xz).
-  - keep the original file in place (--keep).
+    Compressor must:
 
-  Example:
+    - read symlinks (thus --force is needed to gzip, zstd, xz).
+    - keep the original file in place (--keep).
+
+  # Type
 
   ```
-  {
-    xz = "${xz}/bin/xz --force --keep {}";
+  compressDrv :: Derivation -> { formats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrv` usage example
+  ```
+  compressDrv pkgs.spdx-license-list-data.json {
+    formats = ["json"];
+    compressors = {
+      "json" = "${zopfli}/bin/zopfli --keep {}";
+    };
   }
+  =>
+  «derivation /nix/store/...-spdx-license-list-data-3.24.0-compressed.drv»
   ```
 
-  See compressDrvWeb, which is a wrapper on top of compressDrv, for broader use
+  See also pkgs.compressDrvWeb, which is a wrapper on top of compressDrv, for broader usage
   examples.
+  :::
 */
 drv:
 { formats, compressors, ... }:
diff --git a/pkgs/build-support/compress-drv/web.nix b/pkgs/build-support/compress-drv/web.nix
index 6ee15e87d13b..3665e776c6cc 100644
--- a/pkgs/build-support/compress-drv/web.nix
+++ b/pkgs/build-support/compress-drv/web.nix
@@ -4,76 +4,105 @@
   compressDrv,
 }:
 /**
-  # compressDrvWeb compresses a derivation for common web server use.
+  compressDrvWeb compresses a derivation for common web server use.
 
   Useful when one wants to pre-compress certain static assets and pass them to
-  the web server. For example, `pkgs.gamja` creates this derivation:
+  the web server.
 
-      /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/
-      ├── index.2fd01148.js
-      ├── index.2fd01148.js.map
-      ├── index.37aa9a8a.css
-      ├── index.37aa9a8a.css.map
-      ├── index.html
-      └── manifest.webmanifest
+  # Inputs
 
-  `pkgs.compressDrvWeb pkgs.gamja`:
+  `formats` ([String])
 
-      /nix/store/f5ryid7zrw2hid7h9kil5g5j29q5r2f7-gamja-1.0.0-beta.9-compressed
-      ├── index.2fd01148.js -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js
-      ├── index.2fd01148.js.br
-      ├── index.2fd01148.js.gz
-      ├── index.2fd01148.js.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js.map
-      ├── index.2fd01148.js.map.br
-      ├── index.2fd01148.js.map.gz
-      ├── index.37aa9a8a.css -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css
-      ├── index.37aa9a8a.css.br
-      ├── index.37aa9a8a.css.gz
-      ├── index.37aa9a8a.css.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css.map
-      ├── index.37aa9a8a.css.map.br
-      ├── index.37aa9a8a.css.map.gz
-      ├── index.html -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.html
-      ├── index.html.br
-      ├── index.html.gz
-      ├── manifest.webmanifest -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/manifest.webmanifest
-      ├── manifest.webmanifest.br
-      └── manifest.webmanifest.gz
+  : List of file extensions to compress.
 
-  When this `-compressed` directory is passed to a properly configured web
-  server, it will serve those pre-compressed files:
+    Defaults to common formats that compress well.
 
-      $ curl -I -H 'Accept-Encoding: br' https://irc.example.org/
-      <...>
-      content-encoding: br
-      <...>
+  `extraFormats` ([ String ])
+
+  : Extra extensions to compress in addition to `formats`.
+
+  `compressors` ( { ${fileExtension} :: String })
+
+  : Map a desired extension (e.g. `gz`) to a compress program.
+
+  # Type
+
+  ```
+  compressDrvWeb :: Derivation -> { formats :: [ String ]; extraFormats :: [ String ]; compressors :: { ${fileExtension} :: String; } } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.compressDrvWeb` full usage example with `pkgs.gamja` and a webserver
+  ```nix
+
+  For example, building `pkgs.gamja` produces the following output:
+
+    /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/
+    ├── index.2fd01148.js
+    ├── index.2fd01148.js.map
+    ├── index.37aa9a8a.css
+    ├── index.37aa9a8a.css.map
+    ├── index.html
+    └── manifest.webmanifest
+
+  With `pkgs.compressDrvWeb`, one can compress these files:
+
+  ```nix
+  pkgs.compressDrvWeb pkgs.gamja {}
+  =>
+  «derivation /nix/store/...-gamja-compressed.drv»
+  ```
+
+  ```bash
+  /nix/store/f5ryid7zrw2hid7h9kil5g5j29q5r2f7-gamja-1.0.0-beta.9-compressed
+  ├── index.2fd01148.js -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js
+  ├── index.2fd01148.js.br
+  ├── index.2fd01148.js.gz
+  ├── index.2fd01148.js.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.2fd01148.js.map
+  ├── index.2fd01148.js.map.br
+  ├── index.2fd01148.js.map.gz
+  ├── index.37aa9a8a.css -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css
+  ├── index.37aa9a8a.css.br
+  ├── index.37aa9a8a.css.gz
+  ├── index.37aa9a8a.css.map -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.37aa9a8a.css.map
+  ├── index.37aa9a8a.css.map.br
+  ├── index.37aa9a8a.css.map.gz
+  ├── index.html -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/index.html
+  ├── index.html.br
+  ├── index.html.gz
+  ├── manifest.webmanifest -> /nix/store/2wn1qbk8gp4y2m8xvafxv1b2dcdqj8fz-gamja-1.0.0-beta.9/manifest.webmanifest
+  ├── manifest.webmanifest.br
+  └── manifest.webmanifest.gz
+  ```
+
+  When the `-compressed` derivation is passed to a properly configured web server,
+  it enables direct serving of the pre-compressed files.
+
+  ```shell-session
+  $ curl -I -H 'Accept-Encoding: br' https://irc.example.org/
+  <...>
+  content-encoding: br
+  <...>
+  ```
 
   For example, a caddy configuration snippet for gamja to serve
   the static assets (JS, CSS files) pre-compressed:
 
-      virtualHosts."irc.example.org".extraConfig = ''
-        root * ${pkgs.compressDrvWeb pkgs.gamja {}}
-        file_server browse {
-            precompressed br gzip
-        }
-      '';
+  ```nix
+  {
+    virtualHosts."irc.example.org".extraConfig = ''
+      root * ${pkgs.compressDrvWeb pkgs.gamja {}}
+      file_server browse {
+          precompressed br gzip
+      }
+    '';
+  }
+  ```
 
   This feature is also available in nginx via `ngx_brotli` and
   `ngx_http_gzip_static_module`.
-
-  ## Inputs
-
-  `formats` ([String])
-
-  : List of file extensions to compress. Default is common formats that compress
-  well. The list may be expanded.
-
-  `extraFormats` ([String])
-
-  : Extra extensions to compress in addition to `formats`.
-
-  `compressors` (String -> String)
-
-  : See parameter `compressors` of compressDrv.
+  :::
 */
 drv:
 {