From 8215ed02154c3df42f98196e1198184536efa578 Mon Sep 17 00:00:00 2001
From: Philip Taron <philip.taron@gmail.com>
Date: Tue, 18 Mar 2025 12:54:55 -0700
Subject: [PATCH] closureInfo: write a doc comment

To see it, run `:doc closureInfo `nix repl -f.` on Nix 2.26+.
---
 pkgs/build-support/closure-info.nix | 39 ++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/pkgs/build-support/closure-info.nix b/pkgs/build-support/closure-info.nix
index 4ccc2b799415..c255d2feaf13 100644
--- a/pkgs/build-support/closure-info.nix
+++ b/pkgs/build-support/closure-info.nix
@@ -1,15 +1,42 @@
-# This derivation builds two files containing information about the
-# closure of 'rootPaths': $out/store-paths contains the paths in the
-# closure, and $out/registration contains a file suitable for use with
-# "nix-store --load-db" and "nix-store --register-validity
-# --hash-given".
-
 {
   stdenvNoCC,
   coreutils,
   jq,
 }:
 
+/**
+  Produces metadata about the closure of the given root paths.
+
+  1. Total NAR size in `$out/total-nar-size`.
+  2. Registration, suitable for `nix-store --load-db`, in `$out/registration`.
+     Can also be used with `nix-store --register-validity --hash-given`.
+  3. All store paths for the closure in `$out/store-paths`.
+
+  # Inputs
+
+  `rootPaths` ([Path])
+
+  : List of root paths to include in the closure information.
+
+  # Type
+
+  ```
+  closureInfo :: { rootPaths :: [Path]; } -> Derivation
+  ```
+
+  # Examples
+  :::{.example}
+  ## `pkgs.closureInfo` usage example
+  ```
+  pkgs.closureInfo {
+    rootPaths = [ pkgs.hello pkgs.bc pkgs.dwarf2json ];
+  }
+  =>
+  «derivation /nix/store/...-closure-info.drv»
+  ```
+
+  :::
+*/
 { rootPaths }:
 
 assert builtins.langVersion >= 5;