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.

lib/cli.nix

@@ -42,20 +42,34 @@ rec {
   toGNUCommandLineShell =
     options: attrs: lib.escapeShellArgs (toGNUCommandLine options attrs);
 
-  toGNUCommandLine =
-    { mkKey ?
+  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}"
+          else "--${k}",
 
-    , mkOption ?
+    # 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 []
-              else [ (mkKey k) (builtins.toString v) ]
-
-    , mkBool ? k: v: lib.optional v (mkKey k)
-
-    , mkList ? k: v: lib.concatMap (mkOption k) v
+            else [ (mkOptionName k) (lib.generators.mkValueStringDefault {} v) ]
     }:
     options:
       let