improve route syntax docs a bit

doc/basics/route_data.md

@@ -9,9 +9,10 @@ Route data is the key feature of reitit. Routes can have any map-like data attac
                   :handler identity}}]]
 ```
 
-Besides map-like data, raw routes can have any non-sequential route argument after the path. This argument is expanded by `Router` (via `:expand` option) into route data at router creation time. 
+Besides map-like data, raw routes can have any non-sequential route argument after the path. This argument is expanded by `Router` (via `:expand` option) into route data at router creation time.
 
-By default, Keywords are expanded into `:name` and functions into `:handler` keys.
+By default, Keywords are expanded into `:name` (see [Name-based Routing](./name_based_routing.md))
+and functions into `:handler` keys.
 
 ```clj
 (require '[reitit.core :as r])
@@ -117,7 +118,7 @@ Accumulated route data:
       ["/api-docs" ::api-docs]]
      ["/api/ping" ::ping]
      ["/api/pong" ::pong]]))
-     
+
 (r/routes router)
 ; [["/swagger.json" {:no-doc true, :name ::swagger}]
 ;  ["/api-docs" {:no-doc true, :name ::api-docs}]

doc/basics/route_syntax.md

@@ -1,6 +1,9 @@
 # Route Syntax
 
-Routes are defined as vectors of String path and optional (non-sequential) route argument child routes.
+Routes are defined as vectors of:
+- path (a string)
+- optional route data: usually a map, but see [Route Data](./route_data.md)
+- any number of child routes
 
 Routes can be wrapped in vectors and lists and `nil` routes are ignored.
 
@@ -11,53 +14,48 @@ Paths can have path-parameters (`:id`) or catch-all-parameters (`*path`). Parame
 Simple route:
 
 ```clj
-["/ping"]
+["/ping" {:handler ping}]
 ```
 
-Two routes:
+Two routes with more data:
 
 ```clj
-[["/ping"]
- ["/pong"]]
+[["/ping" {:handler ping
+           :cost 300}]
+ ["/pong" {:handler pong
+           :tags #{:game}}]]
 ```
 
-Routes with route arguments:
+Routes with path parameters (see also [Coercion](../coercion/coercion.md) and [Ring Coercion](../ring/coercion.md)):
 
 ```clj
-[["/ping" ::ping]
- ["/pong" {:name ::pong}]]
-```
-
-Routes with path parameters:
-
-```clj
-[["/users/:user-id"]
- ["/api/:version/ping"]]
+[["/users/:user-id" {:handler get-user}]
+ ["/api/:version/ping" {:handler ping-version}]]
 ```
 
 ```clj
-[["/users/{user-id}"]
- ["/files/file-{number}.pdf"]]
+[["/users/{user-id}" {:handler get-user}]
+ ["/files/file-{number}.pdf" {:handler get-pdf}]]
 ```
 
 Route with catch-all parameter:
 
 ```clj
-["/public/*path"]
+["/public/*path" {:handler get-file}]
 ```
 
 ```clj
-["/public/{*path}"]
+["/public/{*path}" {:handler get-file}]
 ```
 
 Nested routes:
 
 ```clj
 ["/api"
  ["/admin" {:middleware [::admin]}
-  ["" ::admin]
-  ["/db" ::db]]
- ["/ping" ::ping]]
+  ["" {:name ::admin}]
+  ["/db" {:name ::db}]]
+ ["/ping" {:name ::ping}]]
 ```
 
 Same routes flattened:
@@ -77,31 +75,31 @@ Reitit does not apply any encoding to your paths. If you need that, you must enc
 Normal path-parameters (`:id`) can start anywhere in the path string, but have to end either to slash `/` (currently hardcoded) or to an end of path string:
 
 ```clj
-[["/api/:version"]
- ["/files/file-:number"]
- ["/user/:user-id/orders"]]
+[["/api/:version" {...}]
+ ["/files/file-:number" {...}]
+ ["/user/:user-id/orders" {...}]]
 ```
 
 Bracket path-parameters can start and stop anywhere in the path-string, the following character is used as a terminator.
 
 ```clj
-[["/api/{version}"]
- ["/files/{name}.{extension}"]
- ["/user/{user-id}/orders"]]
+[["/api/{version}" {...}]
+ ["/files/{name}.{extension}" {...}]
+ ["/user/{user-id}/orders" {...}]]
 ```
 
 Having multiple terminators after a bracket path-path parameter with identical path prefix will cause a compile-time error at router creation:
 
 ```clj
-[["/files/file-{name}.pdf"]            ;; terminator \.
- ["/files/file-{name}-{version}.pdf"]] ;; terminator \-
+[["/files/file-{name}.pdf" {...}]            ;; terminator \.
+ ["/files/file-{name}-{version}.pdf" {...}]] ;; terminator \-
 ```
 
 ### Slash Free Routing
 
 ```clj
-[["broker.{customer}.{device}.{*data}"]
- ["events.{target}.{type}"]]
+[["broker.{customer}.{device}.{*data}" {...}]
+ ["events.{target}.{type}" {...}]]
 ```
 
 ### Generating routes