From 68eb09b68ba2c49be9002b8f776211c6fc3ee42a Mon Sep 17 00:00:00 2001
From: Tommi Reiman <tommi@iki.fi>
Date: Tue, 23 Jan 2018 21:14:47 +0200
Subject: [PATCH] Docs

---
 doc/ring/ring.md | 81 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 72 insertions(+), 9 deletions(-)

diff --git a/doc/ring/ring.md b/doc/ring/ring.md
index 6edb781a..f999150b 100644
--- a/doc/ring/ring.md
+++ b/doc/ring/ring.md
@@ -112,22 +112,85 @@ Middleware is applied correctly:
 ; {:status 200, :body [:api :admin :db :delete :handler]}
 ```
 
-# Not found
+# Default handler
 
-If no routes match, `nil` is returned, which is not understood by Ring.
+By default, if no routes match, `nil` is returned, which is not valid response in Ring:
 
-Enabling custom error messages:
+```clj
+(defn handler [_]
+  {:status 200, :body ""})
+
+(def app
+  (ring/ring-handler
+    (ring/router
+      ["/ping" handler])))
+
+(app {:uri "/invalid"})
+; nil
+```
+
+Setting the default-handler as a second argument to `ring-handler`:
 
 ```clj
 (def app
-  (some-fn
-    (ring/ring-handler
-      (ring/router
-        ["/ping" handler]))
-    (constantly {:status 404})))
+  (ring/ring-handler
+    (ring/router
+      ["/ping" handler])
+    (constantly {:status 404, :body ""})))
 
 (app {:uri "/invalid"})
-; {:status 404}
+; {:status 404, :body ""}
+```
+
+To get more correct http error responses, `ring/create-default-handler` can be used. It differentiates `:not-found` (no route matched), `:method-not-accepted` (no method matched) and `:not-acceptable` (handler returned `nil`).
+
+With defaults:
+
+```clj
+(def app
+  (ring/ring-handler
+    (ring/router
+      [["/ping" {:get handler}]
+       ["/pong" (constantly nil)]])
+    (ring/create-default-handler)))
+
+(app {:request-method :get, :uri "/ping"})
+; {:status 200, :body ""}
+
+(app {:request-method :get, :uri "/"})
+; {:status 404, :body ""}
+
+(app {:request-method :post, :uri "/ping"})
+; {:status 405, :body ""}
+
+(app {:request-method :get, :uri "/pong"})
+; {:status 406, :body ""}
+```
+
+With custom responses:
+
+```clj
+(def app
+  (ring/ring-handler
+    (ring/router
+      [["/ping" {:get handler}]
+       ["/pong" (constantly nil)]])
+    (ring/create-default-handler
+      {:not-found (constantly {:status 404, :body "kosh"})
+       :method-not-allowed (constantly {:status 405, :body "kosh"})
+       :not-acceptable (constantly {:status 406, :body "kosh"})})))
+
+(app {:request-method :get, :uri "/ping"})
+; {:status 200, :body ""}
+
+(app {:request-method :get, :uri "/"})
+; {:status 404, :body "kosh"}
+
+(app {:request-method :post, :uri "/ping"})
+; {:status 405, :body "kosh"}
+
+(app {:request-method :get, :uri "/pong"})
+; {:status 406, :body "kosh"}
 ```
 
 # Async Ring