Error docs

doc/SUMMARY.md

@@ -13,6 +13,7 @@
 * [Route Data](basics/route_data.md)
 * [Route Data Validation](basics/route_data_validation.md)
 * [Route Conflicts](basics/route_conflicts.md)
+* [Error Messages](basics/error_messages.md)
 
 ## Coercion
 

doc/basics/error_messages.md

@@ -0,0 +1,50 @@
+# Error Messages
+
+All exceptions thrown in router creation are caught, formatted and rethrown by the `reitit.core/router` function. Exception formatting is done by the excepton formatter defined by the `:exception` router option.
+
+## Default Errors
+
+The default exception formatting uses `reitit.exception/exception`. It produces single-color, partly human-readable, error messages.
+
+```clj
+(require '[reitit.core :as r])
+
+(r/router
+  [["/ping"]
+   ["/:user-id/orders"]
+   ["/bulk/:bulk-id"]
+   ["/public/*path"]
+   ["/:version/status"]])
+```
+
+![Pretty error](../images/conflicts1.png)
+
+## Pretty Errors
+
+```clj
+[metosin/reitit-dev "0.3.1"]
+```
+
+For human-readable and developer-friendly exception messages, there is `reitit.dev.pretty/exception` (in the `reitit-dev` module). It is inspired by the lovely errors messages of [ELM](https://elm-lang.org/blog/compiler-errors-for-humans) and [ETA](https://twitter.com/jyothsnasrin/status/1037703436043603968) and uses [fipp](https://github.com/brandonbloom/fipp), [expound](https://github.com/bhb/expound) and [spell-spec](https://github.com/bhauman/spell-spec) for most of heavy lifting.
+
+```clj
+(require '[reitit.dev.pretty :as pretty])
+
+(r/router
+  [["/ping"]
+   ["/:user-id/orders"]
+   ["/bulk/:bulk-id"]
+   ["/public/*path"]
+   ["/:version/status"]]
+  {:exception pretty/exception})
+```
+
+![Pretty error](../images/conflicts2.png)
+
+## Extending
+
+Behind the scenes, both error formatters are backed by a multimethod, so they are easy to extend.
+
+## More examples
+
+See the [validating route data](route_data_validation.md) page.

doc/basics/route_data_validation.md

@@ -42,7 +42,7 @@ Failing fast with `clojure.spec` validation turned on:
 
 ### Pretty errors
 
-Turning on [Pretty Errors](pretty_errors.md) will give much nicer error messages:
+Turning on [Pretty Errors](error_messages.md#pretty-errors) will give much nicer error messages:
 
 ```clj
 (require '[reitit.dev.pretty :as pretty])
@@ -81,7 +81,7 @@ Invalid spec value:
   :exception pretty/exception})
 ```
 
-![Pretty error](../images/invalid_roles.png)
+![Invalid Role Error](../images/invalid_roles.png)
 
 ## Closed Specs
 
@@ -103,7 +103,7 @@ Requiring a`:description` and validating using closed specs:
    :exception pretty/exception})
 ```
 
-![Pretty error](../images/closed-spec1.png)
+![Closed Spec error](../images/closed-spec1.png)
 
 It catches also typing errors:
 
@@ -117,5 +117,5 @@ It catches also typing errors:
    :exception pretty/exception})
 ```
 
-![Pretty error](../images/closed-spec2.png)
+![Closed Spec error](../images/closed-spec2.png)