Add docstrings to system.components.handler

src/system/components/handler.clj

@@ -3,10 +3,16 @@
             [lang-utils.core :refer [contains+? ∘]]
             [compojure.core :as compojure]))
 
-(defn- endpoints [component]
+(defn- endpoints
+  "Find all endpoints this component depends on, returns map entries of the form
+  [name component]. An endpoint is a component that define a `:routes` key."
+  [component]
   (filter (comp :routes val) component))
 
 (defn- with-middleware
+  "Returns all endpoints that include middleware. With `flag` being false:
+  returns all enpoints that *don't* include middleware. Works on [name
+  component] map entry pairs."
   ([endpoints]
    (with-middleware endpoints true))
   ([endpoints flag]
@@ -15,7 +21,10 @@
              (fn [[k v]] (not (contains+? v :middleware))))]
      (filter f endpoints))))
 
-(defn- middleware-key [endpoint]
+(defn- middleware-key
+  "Given the endpoint map-entry this returns the key of the
+  middleware dependency if any, or an empty map."
+ [endpoint]
   (reduce-kv (fn [_ k v] (if (contains+? v :middleware) (reduced k) _)) {} (val endpoint)))
 
 (defrecord Handler []
@@ -37,4 +46,29 @@
     (dissoc component :handler)))
 
 (defn new-handler
+  "Creates a handler component. A handler component combines endpoints and
+  middleware into a ring handler function.
+
+  Endpoints should be added as dependencies using `component/using`, the names
+  used for endpoints don't matter, they are recognized by their structure.
+
+  Middleware can be added by depending on a middleware component, either
+  per-endpoint, or once for the complete handler. Per-endpoint middleware can
+  use any name, middleware on the handler must be called `:middleware`.
+
+  The resulting ring handler function is available as `:handler` on the handler
+  component.
+
+  Example:
+
+      (component/system-map
+         :endpoint-a (new-endpoint some-routes)
+         :endpoint-b (-> (new-endpoint other-routes)
+                         (component/using [:endpoint-b-middleware]))
+         :endpoint-b-middleware (new-middleware {:middleware [,,,]})
+         :middleware (new-middleware {:middleware [,,,]})
+         :handler (-> (new-handler)
+                      (component/using [:endpoint-a :endpoint-b :middleware]))
+         :jetty (-> (new-web-server port)
+                    (component/using [:handler])))"
   ([] (->Handler)))