Add docstrings for most commonly used API

[zeitstein]

Adds docstrings to most commonly used API.

I plan on adding docs to defc, <<, etc, as well.

Also have this lengthy http-fx example which I chose not to include. Let me know if I should.

(ev/reg-event rt-ref ::run-api
  (fn [env {:keys [name status]}]
    ;; 'schedules' the http request in ::api-request 
    (ev/queue-fx env ::api-request
      ;; http request definition
      {:request {:uri ["api-point" {:name name :status status}]
                 :method :POST
                 :body {:foo "will be turned into transit!"}}
       ;; defines the event (tx) to trigger if the request is successful
       :on-success {:e ::merge-api-result :foo :bar}})))

(ev/reg-fx rt-ref ::api-request
  ;; makes the http request handler taking [fx-env {:keys [request on-success]}]
  ;; i.e. returns the actual function which runs an http request (XHR)
  (http/make-handler
    ;; config shared by all requests initiated by this handler
    {:on-error {:e ::api-error} ;; tx to run on error
     :base-url "api/" ;; ::run-api url will be "/api/api-point?name=name&status=status
     :request-format :transit ;; will serialize request body with transit
     :response-formats ;; customise response based on content type
     {"application/json"
      (fn [env ^js xhr-req]
        (-> (http/parse-json env xhr-req) ;; the default behaviour, see http-fx/default-response-formats
            ;; turn each json response into clj data
            (js->clj :keywordize-keys true)))}}))

;; this tx runs once the ::api-request completes successfully
(ev/reg-event rt-ref ::merge-api-result
  ;; the event-map will be provided with the properly formatted response of the request in `result`
  (fn [env {:keys [result foo]}] ;; foo from ::run-api
    (assoc-in env [:db :result] result)))

(ev/reg-event rt-ref ::api-error
  (fn [env {:keys [result status sent-request] :as e}]
    (js/console.log "e" e)))

[rschmukler]

@zeitstein thank you for writing this - as someone new to the library this was a very helpful PR to read!