Merge pull request #297990 from hsjobeki/doc/cli

doc: migrate lib.cli to use doc-comments

lib/cli.nix

@@ -1,15 +1,33 @@
 { lib }:
 
 rec {
-  /* Automatically convert an attribute set to command-line options.
+  /**
+    Automatically convert an attribute set to command-line options.
 
     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.
 
-     Example:
+
+    # Inputs
+
+    `options`
+
+    : 1\. Function argument
+
+    `attrs`
+
+    : 2\. Function argument
+
+
+    # Examples
+    :::{.example}
+    ## `lib.cli.toGNUCommandLineShell` usage example
+
+    ```nix
     cli.toGNUCommandLine {} {
       data = builtins.toJSON { id = 0; };
       X = "PUT";
@@ -38,6 +56,9 @@ rec {
       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);