lib/cli: improve documentation, including arguments (#315820)

cli.nix: improve documentation, including arguments

1 files 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,11 +14,11 @@ rec {
 
     `options`
 
-    : 1\. Function argument
+    : How to format the arguments, see `toGNUCommandLine`
 
     `attrs`
 
-    : 2\. Function argument
+    : The attributes to transform into arguments.
 
 
     # Examples
@@ -28,7 +26,7 @@ rec {
     ## `lib.cli.toGNUCommandLineShell` usage example
 
     ```nix
-    cli.toGNUCommandLine {} {
+    cli.toGNUCommandLineShell {} {
       data = builtins.toJSON { id = 0; };
       X = "PUT";
       retry = 3;
@@ -37,16 +35,67 @@ rec {
       silent = false;
       verbose = true;
     }
-    => [
-      "-X" "PUT"
-      "--data" "{\"id\":0}"
-      "--retry" "3"
-      "--url" "https://example.com/foo"
-      "--url" "https://example.com/bar"
-      "--verbose"
-    ]
+    => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
+    ```
 
-    cli.toGNUCommandLineShell {} {
+    :::
+  */
+  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; };
       X = "PUT";
       retry = 3;
@@ -55,38 +104,28 @@ rec {
       silent = false;
       verbose = true;
     }
-    => "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";
+    => [
+      "-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: