lib/cli: mkKey -> mkOptionName, use generators.mkValueStringDefault

Let’s call them by what they are, option names.

`generators.mkValueStringDefault` is a better value string renderer
than plain `toString`.

Also add docs to all options.

1 files changed, 25 insertions, 11 deletions

diff --git a/lib/cli.nix b/lib/cli.nix
index 067ee21696a..c96d4dbb043 100644
--- a/lib/cli.nix
+++ b/lib/cli.nix
@@ -42,20 +42,34 @@ rec {
   toGNUCommandLineShell =
     options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
 
-  toGNUCommandLine =
-    { mkKey ?
-        k: if builtins.stringLength k == 1
-           then "-${k}"
-           else "--${k}"
+  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}",
 
-    , mkOption ?
-        k: v: if v == null
-              then []
-              else [ (mkKey k) (builtins.toString v) ]
+    # 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),
 
-    , mkBool ? k: v: lib.optional v (mkKey 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,
 
-    , 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 []
+            else [ (mkOptionName k) (lib.generators.mkValueStringDefault {} v) ]
     }:
     options:
       let