Document Clojure functions

Author: ajoberstar

src/main/clojure/dev/clojurephant/tooling/api.clj

@@ -1,11 +1,19 @@
 (ns dev.clojurephant.tooling.api
+  "A higher-level API to interact with Gradle's tooling API.
+  Generally, prefer this to use the `dev.clojurephat.tooling.core`
+  API."
   (:require [dev.clojurephant.tooling.core :as core]
             [clojure.edn :as edn]
             [clojure.string :as string]))
 
 (defonce db (atom {}))
 
-(defn connect! [project-dir]
+(defn connect!
+  "Connects to a Gradle project in PROJECT-DIR. If DB
+  already has a connection for this PROJECT-DIR, do
+  nothing. If DB has a connection for another dir, throw.
+  Otherwise create a new connection and store in DB."
+  [project-dir]
   (swap! db (fn [{:keys [dir connection] :as current-db}]
               (cond
                 (nil? connection)
@@ -20,14 +28,21 @@
                 (throw (ex-info "Must close existing connection" {:dir dir})))))
   nil)
 
-(defn close! []
+(defn close!
+  "Closes an existing connection in DB. If there's
+  no existing connection, do nothing."
+  []
   (swap! db (fn [{:keys [connection]}]
               (when connection
                 (.close connection))
               nil))
   nil)
 
-(defn reload-model! []
+(defn reload-model!
+  "Loads the Clojurephant model and stores it in DB. Requires you to
+  have called (connect! ...) before. Reloads model from Gradle config
+  even if model already populated in DB."
+  []
   (swap! db (fn [current-db]
               (if-let [con (:connection current-db)]
                 (let [m (core/wait (core/clojurephant-model con))]
@@ -37,10 +52,17 @@
                                     (select-keys m [:error])))))
                 (throw (ex-info "Cannot get model until connect" {}))))))
 
-(defn repl-output-dir []
+(defn repl-output-dir
+  "Gets the repl output directory. Requires calling
+  (reload-model!) before."
+  []
   (-> @db :model :repl :dir))
 
-(defn ^:private reroot-cljs-build [build new-dir]
+(defn ^:private reroot-cljs-build
+  "Takes a ClojureScript build and re-evaluates the
+  output directories to be relative to the REPL's
+  output directory."
+  [build new-dir]
   (let [old-dir (:output-dir build)
         replacer (fn [dir]
                    (cond
@@ -54,13 +76,19 @@
         (update-in [:output-to] replacer)
         (update-in [:source-map] replacer))))
 
-(defn cljs-all-build-opts []
+(defn cljs-all-build-opts
+  "Returns a map of all ClojureScript build's compiler options.
+  Key is a keyword of the build name, value is a map of compiler
+  options."
+  []
   (let [m (:model @db)
         repl-dir (repl-output-dir)
         builds (:clojurescript m)]
     (into {} (map (fn [[id build]]
                  [id (reroot-cljs-build build repl-dir)]))
           builds)))
 
-(defn cljs-build-opts [id]
+(defn cljs-build-opts
+  "Returns a map of compiler options for the build ID."
+  [id]
   (get (cljs-all-build-opts) id))

src/main/clojure/dev/clojurephant/tooling/cljs.clj

@@ -1,4 +1,7 @@
 (ns dev.clojurephant.tooling.cljs
+  "An API to run ClojureScript builds using configuration
+  from the Gradle build within the REPL. These functions
+  use the ClojureScript build API."
   (:require [dev.clojurephant.tooling.api :as api]
             [cljs.analyzer.api :as ana]
             [cljs.build.api :as build]
@@ -7,41 +10,63 @@
 
 (def registry (atom {}))
 
-(defn build-opts [id]
+(defn build-opts
+  "Returns a map of compiler options for the build ID."
+  [id]
   (api/cljs-build-opts id))
 
-(defn compiler-env! [id]
+(defn compiler-env!
+  "Gets the compiler environment for build ID
+  or sets it to an empty state, if none exists
+  in REGISTRY."
+  [id]
   (let [opts (build-opts id)]
     (-> registry
         (swap! update-in [id :compiler-env]
                (fn [env] (or env (ana/empty-state opts))))
         (get-in [id :compiler-env]))))
 
-(defn build! [id]
+(defn build!
+  "Runs build ID once."
+  [id]
   (let [opts (build-opts id)
         compiler-env (compiler-env! id)]
     (build/build nil opts compiler-env)))
 
-(defn watch! [id]
+(defn watch!
+  "Starts build ID in watch mode. Can be stopped
+  with (stop-watch! id)."
+  [id]
   (let [opts (build-opts id)
         compiler-env (compiler-env! id)
         stop (promise)]
     (swap! registry assoc-in [id :watch-stop] stop)
     (build/watch nil opts compiler-env stop)))
 
-(defn stop-watch! [id]
+(defn stop-watch!
+  "Stops build ID's watch."
+  [id]
   (swap! registry update-in [id :watch-stop]
          (fn [stop] (when stop (deliver stop true))))
   nil)
 
-(defn clean! [id]
+(defn clean!
+  "Cleans build ID. Stops watch, and blows away details
+  in REGISTRY."
+  [id]
   (let [opts (build-opts id)]
     (stop-watch! id)
     (swap! registry dissoc id)
     ;; TODO delete output-dir and output-to
     ))
 
 (defn repl-env!
+  "Gets or sets the repl environment for build ID.
+  With one argument -- the ID -- gets an existing
+  repl env. With two arguments -- the ID and env
+  -- sets the repl env. If build ID already has
+  a repl env, tears it down before replacing it
+  in REGISTRY."
   ([id]
    (get-in @registry [id :repl-env]))
   ([id env]

src/main/clojure/dev/clojurephant/tooling/core.clj

@@ -1,29 +1,44 @@
 (ns dev.clojurephant.tooling.core
+  "The core interaction with Gradle's tooling API is all in
+  this namespace. Generally, this shouldn't be used directly
+  by users."
   (:require [clojure.string :as string]
             [clojure.java.io :as io]
             [dev.clojurephant.tooling.impl.event :as event])
   (:import [org.gradle.tooling GradleConnector ResultHandler]
            [org.gradle.tooling.events ProgressListener]
            [dev.clojurephant.plugin.common ClojurephantModel]))
 
-(defn connect [dir]
+(defn connect
+  "Connects to a Gradle project in DIR.
+  Returns a ProjectConnection."
+  [dir]
   (-> (GradleConnector/newConnector)
       (.forProjectDirectory (io/file dir))
       (.connect)))
 
-(defn tap-listener []
+(defn tap-listener
+  "A progress listener that sends all events
+  to Clojure's tap facility."
+  []
   (let [cache (atom {})]
     (reify ProgressListener
       (statusChanged [this event]
         (println (event/event event cache))))))
 
-(defn collecting-listener [db]
+(defn collecting-listener
+  "A progress listener that collects all events
+  into an atom."
+  [db]
   (let [cache (atom {})]
     (reify ProgressListener
       (statusChanged [this event]
         (swap! db conj (event/event event cache))))))
 
-(defn handler [done db]
+(defn handler
+  "A result handler that sends the result to
+  DONE (a promise) including DB of events."
+  [done db]
   (reify ResultHandler
     (onComplete [this result]
       (deliver done {:result :success
@@ -34,7 +49,10 @@
                      :error failure
                      :events @db}))))
 
-(defn build [con & tasks]
+(defn build
+  "Runs TASKS against the project CON. Returns a map that can
+  be used to either wait for the build to finish or cancel it."
+  [con & tasks]
   (let [cancel-source (GradleConnector/newCancellationTokenSource)
         done (promise)
         db (atom [])]
@@ -43,21 +61,27 @@
         (.setJavaHome (io/file "/usr/lib/jvm/java-18-openjdk-amd64"))
         (.setStandardOutput System/out)
         (.setStandardError System/err)
-        #_(.addProgressListener (tap-listener))
         (.addProgressListener (collecting-listener db))
         (.withCancellationToken (.token cancel-source))
         (.run (handler done db)))
     {:result done
      :cancel cancel-source}))
 
-(defn wait [run]
+(defn wait
+  "Waits for a RUN started with (build ...) to finish and
+  returns the build result."
+  [run]
   @(:result run))
 
-(defn cancel [run]
+(defn cancel
+  "Cancels a RUN started with (build ...)."
+  [run]
   (.cancel (:cancel run))
   run)
 
 (defn task-results
+  "Returns the RUN's task results. If STATE-FILTER is
+  provided you can filter on the task's :state field."
   ([run]
    (task-results run any?))
   ([run state-filter]
@@ -75,19 +99,25 @@
           (filter (fn [t]
                     (state-filter (:result t))))))))
 
-(defn model [con type]
+(defn model
+  "Gets a model of TYPE from project CON. Returns a map that
+  can be used to either wait for the operation to finish or
+  cancel it."
+  [con type]
   (let [cancel-source (GradleConnector/newCancellationTokenSource)
         done (promise)
         db (atom [])]
     (-> (.model con type)
         (.setJavaHome (io/file "/usr/lib/jvm/java-18-openjdk-amd64"))
         (.setStandardOutput System/out)
         (.setStandardError System/err)
-        (.addProgressListener (collecting-listener db))
         (.withCancellationToken (.token cancel-source))
         (.get (handler done db)))
     {:result done
      :cancel cancel-source}))
 
-(defn clojurephant-model [con]
+(defn clojurephant-model
+  "Gets the Clojurephant model. Returns a map that can be
+  used to either wiat for the operation to finish or cancel it."
+  [con]
   (model con ClojurephantModel))

src/main/clojure/dev/clojurephant/tooling/figwheel_main.clj

@@ -1,17 +1,34 @@
 (ns dev.clojurephant.tooling.figwheel-main
+  "An API to start a ClojureScript REPL via Figwheel
+  Main. This uses configuration from Gradle, rather
+  than `<build>.cljs.edn` files.
+
+  As opposed to the `.figwheel-repl` namespace, this
+  does provide the full hot reload workflow."
   (:require [dev.clojurephant.tooling.api :as api]
             [dev.clojurephant.tooling.cljs :as cljs]
             [figwheel.main.api :as fig]))
 
-(defn build-map [id]
+(defn build-map
+  "Gets a build map for Figwheel Main usage. Loads
+  the build configuration from Gradle. Presumes
+  (api/reload-model!) has been called beforehand."
+  [id]
   {:id (name id)
    :options (api/cljs-build-opts id)
    :config {}})
 
-(defn cljs-repl [id]
+(defn cljs-repl
+  "Starts a ClojureScript REPL using
+  Figwheel Main and Piggieback."
+  [id]
   (fig/cljs-repl (name id)))
 
 (defn start
+  "Convenience function to start a ClojureScript
+  REPL with one call. Will connect to and get model
+  config from Gradle, then start the Figwheel Main
+  build and REPL."
   ([] (start :dev))
   ([id]
    (api/connect! ".")

src/main/clojure/dev/clojurephant/tooling/figwheel_repl.clj

@@ -1,19 +1,37 @@
 (ns dev.clojurephant.tooling.figwheel-repl
+  "An API to start a ClojureScript REPL via Figwheel
+  REPL. This only provides the websocket-based REPL,
+  not the full features of Figwheel Main.
+
+  Users may prefer this if they don't want a hot
+  reload workflow or just want fewer moving pices
+  in their process."
   (:require [dev.clojurephant.tooling.api :as api]
             [dev.clojurephant.tooling.cljs :as cljs]
             [cider.piggieback :as piggie]
             [figwheel.repl :as repl]))
 
-(defn repl-env [id]
+(defn repl-env
+  "Creates a new repl environment for build ID.
+  Uses the build configuration from Gradle. Presumes
+  (api/reload-model!) has been called beforehand."
+  [id]
   (let [opts (assoc (cljs/build-opts id)
                     :open-url false)
           env (repl/repl-env* opts)]
       (cljs/repl-env! id env)))
 
-(defn cljs-repl [id]
+(defn cljs-repl
+  "Starts a ClojureScript REPL using
+  Figwheel REPL and Piggieback."
+  [id]
   (piggie/cljs-repl (repl-env id)))
 
 (defn start
+  "Convenience function to start a ClojureScript
+  REPL with one call. Will connect to and get model
+  config from Gradle, pre-build the ClojureScript
+  then start the REPL."
   ([] (start :dev))
   ([id]
    (api/connect! ".")