From 48b4d7e220ae89003a38318bed51e9c656c41189 Mon Sep 17 00:00:00 2001
From: davidnolen <david.nolen@gmail.com>
Date: Sat, 3 Aug 2024 10:41:04 -0400
Subject: [PATCH] * add docstrings to cljs.cli, use clearer names

---
 src/main/clojure/cljs/cli.clj | 60 +++++++++++++++++++++++++++--------
 1 file changed, 46 insertions(+), 14 deletions(-)

diff --git a/src/main/clojure/cljs/cli.clj b/src/main/clojure/cljs/cli.clj
index f404fac9a..295a17dec 100644
--- a/src/main/clojure/cljs/cli.clj
+++ b/src/main/clojure/cljs/cli.clj
@@ -341,6 +341,8 @@ present"
           inits)))))
 
 (defn default-main
+  "Default handler for the --main flag. Will start REPL, invoke -main with the
+  supplied arguments."
   [repl-env {:keys [main script args repl-env-options options inits] :as cfg}]
   (let [opts   (cond-> options
                  (not (:output-dir options))
@@ -542,13 +544,23 @@ present"
   ((::compile (repl/-repl-options (repl-env)) default-compile)
     repl-env (merge cfg {:args args :ns ns})))
 
-(defn get-options [commands k]
-  (if (= :all k)
+(defn get-options
+  "Given a commands map and a phase (:init or :main), return all flags
+  which can be handled as a set. If phase is :all will return the entire
+  flag set (:init + :main)."
+  [commands phase]
+  (if (= :all phase)
     (into (get-options commands :main) (get-options commands :init))
-    (-> (get commands (keyword (str (name k) "-dispatch")))
+    (-> (get commands (keyword (str (name phase) "-dispatch")))
       keys set)))
 
-(defn bool-init-options [commands]
+(defn get-flags-set
+  "See a get-options, this just provides a better name."
+  [commands phase]
+  (get-options commands phase))
+
+(defn bool-init-options
+  [commands]
   (reduce
     (fn [ret [flags config]]
       (cond-> ret
@@ -556,20 +568,26 @@ present"
         (into flags)))
     #{} (:init commands)))
 
-(defn dispatch? [commands k opt]
-  (contains? (get-options commands k) opt))
+(defn dispatch?
+  "Given a commands map, a phase (:init or :main) and a command line flag,
+  return true if the flag has a handler."
+  [commands phase opt]
+  (contains? (get-flags-set commands phase) opt))
 
 (defn add-commands
+  "Given commands map (see below), create a commands map with :init-dispatch
+  and :main-dispatch keys where short and long arguments are mapped individually
+  to their processing fn."
   ([commands]
     (add-commands {:main-dispatch nil :init-dispatch nil} commands))
   ([commands {:keys [groups main init]}]
-   (letfn [(merge-dispatch [st k options]
-             (update-in st [k]
+   (letfn [(merge-dispatch [commands dispatch-key options]
+             (update-in commands [dispatch-key]
                (fn [m]
                  (reduce
-                   (fn [ret [cs csm]]
+                   (fn [ret [flag-names flag-config]]
                      (merge ret
-                       (zipmap cs (repeat (:fn csm)))))
+                       (zipmap flag-names (repeat (:fn flag-config)))))
                    m options))))]
      (-> commands
        (update-in [:groups] merge groups)
@@ -578,7 +596,12 @@ present"
        (merge-dispatch :init-dispatch init)
        (merge-dispatch :main-dispatch main)))))
 
-(def default-commands
+(def ^{:doc "Default commands for ClojureScript REPLs. :groups are to support
+printing organized output for --help. a :main option must come at the end, they
+specify things like running a -main fn, compile, repl, or web serving. Sometimes
+:main options can use be used together (i.e. --compile --repl), but this is not
+generic - the combinations must be explicitly supported"}
+  default-commands
   (add-commands
     {:groups {::main&compile {:desc "init options"
                               :pseudos
@@ -662,9 +685,14 @@ present"
       ["-h" "--help" "-?"]     {:fn help-opt
                                 :doc "Print this help message and exit"}}}))
 
-(defn normalize [commands args]
+(defn normalize
+  "Given a commands map (flag + value -> option processor fn) and the sequence of
+  command line arguments passed to the process, normalize it. Boolean flags don't
+  need to specify anything, insert the implied trues and return the normalized
+  command line arguments."
+  [commands args]
   (letfn [(normalize* [args*]
-            (if (not (contains? (get-options commands :main) (first args*)))
+            (if (not (contains? (get-flags-set commands :main) (first args*)))
               (let [pred (complement (bool-init-options commands))
                     [pre post] ((juxt #(take-while pred %)
                                   #(drop-while pred %))
@@ -685,7 +713,11 @@ present"
         args'
         (recur args' (normalize* args'))))))
 
-(defn merged-commands [repl-env]
+(defn merged-commands
+  "Given a repl environment combine the default commands with the custom
+  REPL commands. Commands are a mapping from a command line argument
+  (flag + value) to a function to handle that particular flag + value."
+  [repl-env]
   (add-commands default-commands
     (::commands (repl/repl-options (repl-env)))))