docs: review and update docstrings (#41)

This exercise helped me to understand the API more deeply, hopefully it
will help our users too.

The biggest challenge was documenting `clj-http.lite.client/request`.
Its previous docstring was way too vague for me to understand, as a
user, what is available.

Also challenging is the lack of definition of the supported API.
I'm guessing our documented API is currently including lots of
unnecessary internals.

I reviewed all existing docstrings and updated where I thought I could
be clearer and/or more consistent. I added no new docstrings.

Also: added cljdoc.edn to explicitly list our docs.

Closes #36

Author: lread

doc/cljdoc.edn

@@ -0,0 +1,3 @@
+{:cljdoc.doc/tree
+ [["Readme" {:file "README.md"}]
+  ["Changelog" {:file "CHANGELOG.md"}]]}

src/clj_http/lite/client.clj

@@ -1,5 +1,8 @@
 (ns clj-http.lite.client
-  "Batteries-included HTTP client."
+  "Batteries-included HTTP client.
+
+  Among the many functions here you'll likely be most interested in
+  [[get]] [[head]] [[put]] [[post]] [[delete]] or the slightly lower level [[request]]."
   (:require [clj-http.lite.core :as core]
             [clj-http.lite.links :refer [wrap-links]]
             [clj-http.lite.util :as util]
@@ -233,8 +236,7 @@
       (client req))))
 
 (defn wrap-request
-  "Returns a battaries-included HTTP request function coresponding to the given
-   core client. See client/client."
+  "Returns a batteries-included HTTP request function."
   [request]
   ;; note to the uninitiated: wrapper behaviour is applied to requests in order listed here but
   ;; from last to first
@@ -257,51 +259,101 @@
       wrap-links
       wrap-unknown-host))
 
-(def #^{:doc
-        "Executes the HTTP request corresponding to the given map and returns
-   the response map for corresponding to the resulting HTTP response.
-
-   In addition to the standard Ring request keys, the following keys are also
-   recognized:
-   * :url
-   * :method
-   * :query-params
-   * :basic-auth
-   * :content-type
-   * :accept
-   * :accept-encoding
-   * :as
-
-  The following additional behaviors over also automatically enabled:
-   * Exceptions are thrown for status codes other than 200-207, 300-303, or 307
-   * Gzip and deflate responses are accepted and decompressed
-   * Input and output bodies are coerced as required and indicated by the :as
-     option."}
+(def ^{:arglists '([req])}
   request
+  "Returns response map for executed HTTP `req` map.
+
+   Notice that some `req` key entries will be overwritten by automatic conversion to other key entries:
+
+   Request method
+   * `:method` -  ex. `:get`,`:head`,`:post`,`:put`,`:delete`, converts to `:request-method` with same value
+
+   Request URL
+   * `:url` - ex. `\"https://joe:blow@example.com:443/some/path?q=clojure\"`, converts to:
+     * `:scheme` - protocol `:https`
+     * `:server-name` - host `\"example.com\"`
+     * `:server-port` - `443` (if not specified, will be inferred from `:scheme`)
+     * `:uri` - path `\"/some/path\"`
+     * `:user-info` -  `\"joe:blow\"`, converts to:
+       * `:basic-auth` - which automatically converts to appropriate `:headers`
+     * `:query-string` - `\"q=clojure\"`
+   * `:query-params` - ex. `{\"q\" \"clojure\"}` or `{:q \"clojure\"}` converts to `:query-string` (see above)
+
+   Request body & headers
+   * `:body` - can be a string, byte array, File or input stream
+   * `:body-encoding` - charset ex. `\"UTF-16\"`, defaults to `\"UTF-8\"`, iff `:body` is string converts to:
+      * `:body` encoded in charset
+      * `:character-encoding` set to charset which converts to appropriate `:headers` iff `:content-type` also set
+   * `:content-type` - media type of request body, converts to appropriate `:headers` entry, specify:
+     * keyword as shorthand, ex. `:json` for `\"application/json\"`
+     * string for verboten, ex. `\"text/html\"`
+   * `:form-params` - ex. `{\"q\" \"clojure\"}` or `{:q \"clojure\"}`, iff `:method` is `:post`: converts to:
+      * urlencoded `:body`
+      * appropriate `:headers` entry
+   * `:oauth-token` - bearer authorization token, ex. `\"my70k3nh3r3\"`, converts to appropriate `:headers` entry
+   * `:basic-auth` - basic authentication, converts to appropriate `:headers` entry, (see also `:url` and `:user-info`), specify:
+     * vector `[\"uname\" \"pass\"]` becomes `\"uname:pass\"`
+     * use string for verboten
+   * `:accept-encoding` - vector of accepted response encodings, ex. `[:gzip :deflate :identity]`, converts to appropriate `:headers` entry
+   * `:accept` - accept response of media type, converts to appropriate `:headers` entry, specify
+     * keyword as shorthand, ex. `:json` for `\"application/json\"`
+     * string for verboten, ex. `\"text/html\"`
+   * `:headers` - explicitly set request headers, ex. `{\"Cache-Control\" \"no-cache\"}`
+
+   Request behaviour
+   * `:as` - specifies how response body should be coerced:
+     * `:stream`
+     * `:byte-array`
+     * `:auto` - to string decoded with `charset` in response `:headers` `content-type` `charset` else UTF-8
+     * `\"charset\"` - to string decoded with `charset` ex. `\"utf-16\"`
+     * else - to string decoded with UTF-8
+   * `:follow-redirects` - specify `false` to not follow response redirects
+   * `:throw-exceptions` - specify `false` to not throw on https status error codes
+   * `:ignore-unknown-host?` - specify `true` to not throw on unknown host
+   * `:insecure?` - allow connection with an invalid SSL certificate
+   * `:conn-timeout` - number of milliseconds to wait to establish a connection
+   * `:socket-timeout` - number of milliseconds to wait for data to be available to read
+   * `:save-request?` - specify `true` to include ultimate converted `:request` used in response map
+   * `:chunk-size` - in bytes, enables streaming of HTTP request body with chunk-size bytes,
+see [JDK docs](https://docs.oracle.com/javase/8/docs/api/java/net/HttpURLConnection.html#setChunkedStreamingMode-int-)
+for details
+
+  Response map keys:
+  * `:status` - http status code, see `:throw-exceptions` above
+  * `:headers` - response headers
+  * `:body` - response body, gzip and deflate responses are accepted and decompressed. See `:as` above.
+  * `:request` - see `:save-request?` above
+
+  See [README](/README.md#usage) for example usages."
   (wrap-request #'core/request))
 
 (defn get
-  "Like #'request, but sets the :method and :url as appropriate."
+  "Executes HTTP GET request for `url` and, optionally, more `req` attributes.
+  See [[request]]."
   [url & [req]]
   (request (merge req {:method :get :url url})))
 
 (defn head
-  "Like #'request, but sets the :method and :url as appropriate."
+  "Executes HTTP HEAD request for `url` and, optionally, more `req` attributes.
+  See [[request]]."
   [url & [req]]
   (request (merge req {:method :head :url url})))
 
 (defn post
-  "Like #'request, but sets the :method and :url as appropriate."
+  "Executes HTTP POST request for `url` and, optionally, more `req` attributes.
+  See [[request]]."
   [url & [req]]
   (request (merge req {:method :post :url url})))
 
 (defn put
-  "Like #'request, but sets the :method and :url as appropriate."
+  "Executes HTTP PUT request for `url` and, optionally, more `req` attributes.
+  See [[request]]."
   [url & [req]]
   (request (merge req {:method :put :url url})))
 
 (defn delete
-  "Like #'request, but sets the :method and :url as appropriate."
+  "Executes HTTP DELETE request for `url` and, optionally, more `req` attributes.
+  See [[request]]."
   [url & [req]]
   (request (merge req {:method :delete :url url})))
 

src/clj_http/lite/core.clj

@@ -7,9 +7,9 @@
 (set! *warn-on-reflection* true)
 
 (defn parse-headers
-  "Takes a URLConnection and returns a map of names to values.
+  "Returns a map of names to values for URLConnection `conn`.
 
-   If a name appears more than once (like `set-cookie`) then the value
+   If a header name appears more than once (like `set-cookie`) then the value
    will be a vector containing the values in the order they appeared
    in the headers."
   [conn]
@@ -26,8 +26,8 @@
                     (vec v))))))))
 
 (defn- coerce-body-entity
-  "Coerce the http-entity from an HttpResponse to either a byte-array, or a
-  stream that closes itself and the connection manager when closed."
+  "Return body response from HttpURLConnection `conn` coerced to either a byte-array,
+  or a stream."
   [{:keys [as]} conn]
   (let [ins (try
               (.getInputStream ^HttpURLConnection conn)
@@ -74,11 +74,8 @@
 (def-insecure)
 
 (defn request
-  "Executes the HTTP request corresponding to the given Ring request map and
-   returns the Ring response map corresponding to the resulting HTTP response.
-
-   Note that where Ring uses InputStreams for the request and response bodies,
-   the clj-http uses ByteArrays for the bodies."
+  "Executes the HTTP request corresponding to the given Ring `req` map and
+   returns the Ring response map corresponding to the resulting HTTP response."
   [{:keys [request-method scheme server-name server-port uri query-string
            headers content-type character-encoding body socket-timeout
            conn-timeout insecure? save-request? follow-redirects

src/clj_http/lite/links.clj

@@ -54,8 +54,10 @@
     response))
 
 (defn wrap-links
-  "Add a :links key to the response map that contains parsed Link headers. The
-  links will be represented as a map, with the 'rel' value being the key. The
+  "Returns request wrapper fn for `client` that adds
+  a `:links` key to the response map that contains parsed link headers.
+
+  The links are returned as a map, with the 'rel' value being the key. The
   URI is placed under the 'href' key, to mimic the HTML link element.
 
   e.g. Link: <http://example.com/page2.html>; rel=next; title=\"Page 2\"

src/clj_http/lite/util.clj

@@ -9,29 +9,29 @@
 (set! *warn-on-reflection* true)
 
 (defn utf8-bytes
-  "Returns the UTF-8 bytes corresponding to the given string."
+  "Returns the UTF-8 bytes for string `s`."
   [#^String s]
   (.getBytes s "UTF-8"))
 
 (defn utf8-string
-  "Returns the String corresponding to the UTF-8 decoding of the given bytes."
+  "Returns the string for UTF-8 decoding of bytes `b`."
   [#^"[B" b]
   (String. b "UTF-8"))
 
 (defn url-decode
-  "Returns the form-url-decoded version of the given string, using either a
-  specified encoding or UTF-8 by default."
+  "Returns the form-url-decoded version of `encoded` string, using either a
+  specified `encoding` or UTF-8 by default."
   [^String encoded & [encoding]]
   (let [^String encoding (or encoding "UTF-8")]
     (URLDecoder/decode encoded encoding)))
 
 (defn url-encode
-  "Returns an UTF-8 URL encoded version of the given string."
+  "Returns an UTF-8 URL encoded version of `unencoded` string."
   [^String unencoded]
   (URLEncoder/encode unencoded "UTF-8"))
 
 (defmacro base64-encode
-  "Encode an array of bytes into a base64 encoded string."
+  "Encode an array of `unencoded` bytes into a base64 encoded string."
   [unencoded]
   (if (try (import 'javax.xml.bind.DatatypeConverter)
            (catch Exception _))
@@ -41,7 +41,7 @@
       `(.encodeToString (java.util.Base64/getEncoder) ~unencoded))))
 
 (defn to-byte-array
-  "Returns a byte array for the InputStream provided."
+  "Returns a byte array for InputStream `is`."
   [is]
   (let [chunk-size 8192
         baos (ByteArrayOutputStream.)
@@ -54,15 +54,15 @@
 
 
 (defn gunzip
-  "Returns a gunzip'd version of the given byte array."
+  "Returns a gunzip'd version of byte array `b`."
   [b]
   (when b
     (if (instance? InputStream b)
       (GZIPInputStream. b)
       (to-byte-array (GZIPInputStream. (ByteArrayInputStream. b))))))
 
 (defn gzip
-  "Returns a gzip'd version of the given byte array."
+  "Returns a gzip'd version byte array `b`."
   [b]
   (when b
     (let [baos (ByteArrayOutputStream.)
@@ -72,13 +72,13 @@
       (.toByteArray baos))))
 
 (defn inflate
-  "Returns a zlib inflate'd version of the given byte array."
+  "Returns a zlib inflate'd version byte array `b`."
   [b]
   (when b
     (to-byte-array (InflaterInputStream. (ByteArrayInputStream. b)))))
 
 (defn deflate
-  "Returns a deflate'd version of the given byte array."
+  "Returns a deflate'd version byte array `b`."
   [b]
   (when b
     (to-byte-array (DeflaterInputStream. (ByteArrayInputStream. b)))))