From 19a3000c32a2a58b9a96f8b35eca8faff0ad00c7 Mon Sep 17 00:00:00 2001
From: Rob Pilling <robpilling@gmail.com>
Date: Thu, 30 May 2024 08:15:32 +0100
Subject: [PATCH] cli.nix: improve documentation, including arguments

---
 lib/cli.nix | 107 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 71 insertions(+), 36 deletions(-)

diff --git a/lib/cli.nix b/lib/cli.nix
index 311037c519a6..b65131ac1a1b 100644
--- a/lib/cli.nix
+++ b/lib/cli.nix
@@ -7,8 +7,6 @@ rec {
     This helps protect against malformed command lines and also to reduce
     boilerplate related to command-line construction for simple use cases.
 
-    `toGNUCommandLine` returns a list of nix strings.
-
     `toGNUCommandLineShell` returns an escaped shell string.
 
 
@@ -16,17 +14,86 @@ rec {
 
     `options`
 
-    : 1\. Function argument
+    : How to format the arguments, see `toGNUCommandLine`
 
     `attrs`
 
-    : 2\. Function argument
+    : The attributes to transform into arguments.
 
 
     # Examples
     :::{.example}
     ## `lib.cli.toGNUCommandLineShell` usage example
 
+    ```nix
+    cli.toGNUCommandLineShell {} {
+      data = builtins.toJSON { id = 0; };
+      X = "PUT";
+      retry = 3;
+      retry-delay = null;
+      url = [ "https://example.com/foo" "https://example.com/bar" ];
+      silent = false;
+      verbose = true;
+    }
+    => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
+    ```
+
+    :::
+  */
+  toGNUCommandLineShell =
+    options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
+
+  /**
+    Automatically convert an attribute set to a list of command-line options.
+
+    `toGNUCommandLine` returns a list of string arguments.
+
+
+    # Inputs
+
+    `options`
+
+    : How to format the arguments, see below.
+
+    `attrs`
+
+    : The attributes to transform into arguments.
+
+    # Options
+
+    `mkOptionName`
+
+    : How to string-format the option name;
+    By default one character is a short option (`-`), more than one characters a long option (`--`).
+
+    `mkBool`
+
+    : How to format a boolean value to a command list;
+    By default it’s a flag option (only the option name if true, left out completely if false).
+
+    `mkList`
+
+    : How to format a list value to a command list;
+    By default the option name is repeated for each value and `mkOption` is applied to the values themselves.
+
+
+    `mkOption`
+
+    : How to format any remaining value to a command list;
+    On the toplevel, booleans and lists are handled by `mkBool` and `mkList`, though they can still appear as values of a list.
+    By default, everything is printed verbatim and complex types are forbidden (lists, attrsets, functions). `null` values are omitted.
+
+    `optionValueSeparator`
+
+    : How to separate an option from its flag;
+    By default, there is no separator, so option `-c` and value `5` would become ["-c" "5"].
+    This is useful if the command requires equals, for example, `-c=5`.
+
+
+    # Examples
+    :::{.example}
+    ## `lib.cli.toGNUCommandLine` usage example
+
     ```nix
     cli.toGNUCommandLine {} {
       data = builtins.toJSON { id = 0; };
@@ -45,48 +112,20 @@ rec {
       "--url" "https://example.com/bar"
       "--verbose"
     ]
-
-    cli.toGNUCommandLineShell {} {
-      data = builtins.toJSON { id = 0; };
-      X = "PUT";
-      retry = 3;
-      retry-delay = null;
-      url = [ "https://example.com/foo" "https://example.com/bar" ];
-      silent = false;
-      verbose = true;
-    }
-    => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
     ```
 
     :::
   */
-  toGNUCommandLineShell =
-    options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
-
   toGNUCommandLine = {
-    # how to string-format the option name;
-    # by default one character is a short option (`-`),
-    # more than one characters a long option (`--`).
     mkOptionName ?
       k: if builtins.stringLength k == 1
           then "-${k}"
           else "--${k}",
 
-    # how to format a boolean value to a command list;
-    # by default it’s a flag option
-    # (only the option name if true, left out completely if false).
     mkBool ? k: v: lib.optional v (mkOptionName k),
 
-    # how to format a list value to a command list;
-    # by default the option name is repeated for each value
-    # and `mkOption` is applied to the values themselves.
     mkList ? k: v: lib.concatMap (mkOption k) v,
 
-    # how to format any remaining value to a command list;
-    # on the toplevel, booleans and lists are handled by `mkBool` and `mkList`,
-    # though they can still appear as values of a list.
-    # By default, everything is printed verbatim and complex types
-    # are forbidden (lists, attrsets, functions). `null` values are omitted.
     mkOption ?
       k: v: if v == null
             then []
@@ -95,10 +134,6 @@ rec {
             else
               [ "${mkOptionName k}${optionValueSeparator}${lib.generators.mkValueStringDefault {} v}" ],
 
-    # how to separate an option from its flag;
-    # by default, there is no separator, so option `-c` and value `5`
-    # would become ["-c" "5"].
-    # This is useful if the command requires equals, for example, `-c=5`.
     optionValueSeparator ? null
     }:
     options: