From 6bcb2b90eda11aedeb5280d4cadc43e1dfbc3d3d Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Fri, 22 Mar 2024 09:54:17 +0100
Subject: [PATCH] doc: migrate lib.cli to use doc-comments

---
 lib/cli.nix | 87 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 54 insertions(+), 33 deletions(-)

diff --git a/lib/cli.nix b/lib/cli.nix
index c96d4dbb0432..fcffacb5ea99 100644
--- a/lib/cli.nix
+++ b/lib/cli.nix
@@ -1,43 +1,64 @@
 { 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.
+    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.
+    `toGNUCommandLine` returns a list of nix strings.
 
-     Example:
-       cli.toGNUCommandLine {} {
-         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` returns an escaped shell string.
 
-       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'";
+
+    # 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";
+      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"
+    ]
+
+    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);