From b4b02d084f066d6391074ac807e532e36e4eccd9 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 7 Jul 2023 11:40:40 +0200
Subject: [PATCH] fetchClosure: Interleave the examples in the docs

---
 src/libexpr/primops/fetchClosure.cc | 79 ++++++++++++++---------------
 1 file changed, 37 insertions(+), 42 deletions(-)

diff --git a/src/libexpr/primops/fetchClosure.cc b/src/libexpr/primops/fetchClosure.cc
index 22bae19b7..7fe8203f4 100644
--- a/src/libexpr/primops/fetchClosure.cc
+++ b/src/libexpr/primops/fetchClosure.cc
@@ -211,52 +211,42 @@ static RegisterPrimOp primop_fetchClosure({
     .name = "__fetchClosure",
     .args = {"args"},
     .doc = R"(
-      Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache.
+      Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache, and return the store path as a string with context.
 
-      This function can be used in three ways:
+      This function can be invoked in three ways, that we will discuss in order of preference.
 
-      - Fetch any store path and rewrite it to a fully content-addressed store path.
-
-        Example:
-
-        ```nix
-        builtins.fetchClosure {
-            fromStore = "https://cache.nixos.org";
-            fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
-            toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
-        }
-        ```
-
-      - Fetch a content-addressed store path.
+      **Fetch a content-addressed store path**
 
       Example:
 
-        ```nix
-        builtins.fetchClosure {
-            fromStore = "https://cache.nixos.org";
-            fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
-        }
-        ```
+      ```nix
+      builtins.fetchClosure {
+        fromStore = "https://cache.nixos.org";
+        fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
+      }
+      ```
 
-      - Fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) as is. This depends on user configuration, which is less preferable.
+      This is the simplest invocation, and it does not require the user of the expression to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
 
-        Example:
+      If your store path is [input addressed](@docroot@/glossary.md#gloss-input-addressed-store-object) instead of content addressed, consider the other two invocations.
 
-        ```nix
-        builtins.fetchClosure {
-            fromStore = "https://cache.nixos.org";
-            fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
-            inputAddressed = true;
-        }
-        ```
+      **Fetch any store path and rewrite it to a fully content-addressed store path**
 
-      **Rewriting a store path**
+      Example:
 
-      This first example fetches `/nix/store/r2jd...` from the specified binary cache,
+      ```nix
+      builtins.fetchClosure {
+        fromStore = "https://cache.nixos.org";
+        fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
+        toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
+      }
+      ```
+
+      This example fetches `/nix/store/r2jd...` from the specified binary cache,
       and rewrites it into the content-addressed store path
       `/nix/store/ldbh...`.
 
-      By rewriting the store paths, you can add the contents to any store without requiring that you or perhaps your users configure any extra trust.
+      Like the previous example, no extra configuration or privileges are required.
 
       To find out the correct value for `toPath` given a `fromPath`,
       use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
@@ -268,20 +258,25 @@ static RegisterPrimOp primop_fetchClosure({
 
       Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
 
-      **Not rewriting**
+      **Fetch an input-addressed store path as is**
 
-      `toPath` may be omitted when either
-       - `fromPath` is already content-addressed, or
-       - `inputAddressed = true;` is set.
+      Example:
 
-      Fetching an [input addressed path](@docroot@/glossary.md#gloss-input-addressed-store-object) is not recommended because it requires that the source be trusted by the Nix configuration.
+      ```nix
+      builtins.fetchClosure {
+        fromStore = "https://cache.nixos.org";
+        fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
+        inputAddressed = true;
+      }
+      ```
+
+      It is possible to fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) and return it as is.
+      However, this is the least preferred way of invoking `fetchClosure`, because it requires that the input-addressed paths are trusted by the Nix configuration.
 
       **`builtins.storePath`**
 
-      This function is similar to [`builtins.storePath`](#builtins-storePath) in that it
-      allows you to use a previously built store path in a Nix
-      expression. However, it is more reproducible because it requires
-      specifying a binary cache from which the path can be fetched.
+      `fetchClosure` is similar to [`builtins.storePath`](#builtins-storePath) in that it allows you to use a previously built store path in a Nix expression.
+      However, `fetchClosure` is more reproducible because it specifies a binary cache from which the path can be fetched.
       Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
     )",
     .fun = prim_fetchClosure,