From 7cc8f84297fa20abd2ccc6fb6099fc047429837d Mon Sep 17 00:00:00 2001
From: Tommi Reiman <tommi@iki.fi>
Date: Wed, 22 Aug 2018 19:39:04 +0300
Subject: [PATCH] better docs

---
 .../src/reitit/ring/middleware/exception.clj  |  4 +-
 .../src/reitit/ring/middleware/muuntaja.clj   | 42 ++++++++++++++++++-
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/modules/reitit-middleware/src/reitit/ring/middleware/exception.clj b/modules/reitit-middleware/src/reitit/ring/middleware/exception.clj
index d89a1c20..f61aa3db 100644
--- a/modules/reitit-middleware/src/reitit/ring/middleware/exception.clj
+++ b/modules/reitit-middleware/src/reitit/ring/middleware/exception.clj
@@ -109,12 +109,14 @@
    (-> options wrap handler)))
 
 (def exception-middleware
+  "A preconfigured exception handling Middleware. To configure the exceptions handlers, use
+  `create-exception-handler` instead."
   {:name ::exception
    :spec ::spec
    :wrap (wrap default-handlers)})
 
 (defn create-exception-middleware
-  "Creates a reitit middleware that catches all exceptions. Takes a map
+  "Creates a Middleware that catches all exceptions. Takes a map
   of `identifier => exception request => response` that is used to select
   the exception handler for the thown/raised exception identifier. Exception
   idenfier is either a `Keyword` or a Exception Class.
diff --git a/modules/reitit-middleware/src/reitit/ring/middleware/muuntaja.clj b/modules/reitit-middleware/src/reitit/ring/middleware/muuntaja.clj
index fcb580c9..28e02e8f 100644
--- a/modules/reitit-middleware/src/reitit/ring/middleware/muuntaja.clj
+++ b/modules/reitit-middleware/src/reitit/ring/middleware/muuntaja.clj
@@ -9,6 +9,21 @@
 (defn- displace [x] (with-meta x {:displace true}))
 
 (def format-middleware
+  "Middleware for content-negotiation, request and response formatting.
+
+  Negotiates a request body based on `Content-Type` header and response body based on
+  `Accept`, `Accept-Charset` headers. Publishes the negotiation results as `:muuntaja/request`
+  and `:muuntaja/response` keys into the request.
+
+  Decodes the request body into `:body-params` using the `:muuntaja/request` key in request
+  if the `:body-params` doesn't already exist.
+
+  Encodes the response body using the `:muuntaja/response` key in request if the response
+  doesn't have `Content-Type` header already set.
+
+  | key          | description |
+  | -------------|-------------|
+  | `:muuntaja`  | `muuntaja.core/Muuntaja` instance, does not mount if not set."
   {:name ::format
    :spec ::spec
    :compile (fn [{:keys [muuntaja]} _]
@@ -18,6 +33,15 @@
                  :wrap #(muuntaja.middleware/wrap-format % muuntaja)}))})
 
 (def format-negotiate-middleware
+  "Middleware for content-negotiation.
+
+  Negotiates a request body based on `Content-Type` header and response body based on
+  `Accept`, `Accept-Charset` headers. Publishes the negotiation results as `:muuntaja/request`
+  and `:muuntaja/response` keys into the request.
+
+  | key          | description |
+  | -------------|-------------|
+  | `:muuntaja`  | `muuntaja.core/Muuntaja` instance, does not mount if not set."
   {:name ::format-negotiate
    :spec ::spec
    :compile (fn [{:keys [muuntaja]} _]
@@ -25,14 +49,30 @@
                 {:wrap #(muuntaja.middleware/wrap-format-negotiate % muuntaja)}))})
 
 (def format-request-middleware
+  "Middleware for request formatting.
+
+  Decodes the request body into `:body-params` using the `:muuntaja/request` key in request
+  if the `:body-params` doesn't already exist.
+
+  | key          | description |
+  | -------------|-------------|
+  | `:muuntaja`  | `muuntaja.core/Muuntaja` instance, does not mount if not set."
   {:name ::format-request
    :spec ::spec
    :compile (fn [{:keys [muuntaja]} _]
               (if muuntaja
                 {:data {:swagger {:consumes (displace (m/decodes muuntaja))}}
                  :wrap #(muuntaja.middleware/wrap-format-request % muuntaja)}))})
-
+©
 (def format-response-middleware
+  "Middleware for response formatting.
+
+  Encodes the response body using the `:muuntaja/response` key in request if the response
+  doesn't have `Content-Type` header already set.
+
+  | key          | description |
+  | -------------|-------------|
+  | `:muuntaja`  | `muuntaja.core/Muuntaja` instance, does not mount if not set."
   {:name ::format-response
    :spec ::spec
    :compile (fn [{:keys [muuntaja]} _]