doc: improve route_syntax.md

- don't use no-data no-child routes as examples, they confuse newbies
- spell out what route data can be
- link to other 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,43 +14,38 @@ 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"]
+[["/ping" {:handler ping
- ["/pong"]]
+           :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]
+[["/users/:user-id" {:handler get-user}]
- ["/pong" {:name ::pong}]]
+ ["/api/:version/ping" {:handler ping-version}]]
-```
-
-Routes with path parameters:
-
-```clj
-[["/users/:user-id"]
- ["/api/:version/ping"]]
 ```
 
 ```clj
-[["/users/{user-id}"]
+[["/users/{user-id}" {:handler get-user}]
- ["/files/file-{number}.pdf"]]
+ ["/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:
@@ -55,9 +53,9 @@ Nested routes:
 ```clj
 ["/api"
  ["/admin" {:middleware [::admin]}
-  ["" ::admin]
+  ["" {:name ::admin}]
-  ["/db" ::db]]
+  ["/db" {:name ::db}]]
- ["/ping" ::ping]]
+ ["/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"]
+[["/api/:version" {...}]
- ["/files/file-:number"]
+ ["/files/file-:number" {...}]
- ["/user/:user-id/orders"]]
+ ["/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}"]
+[["/api/{version}" {...}]
- ["/files/{name}.{extension}"]
+ ["/files/{name}.{extension}" {...}]
- ["/user/{user-id}/orders"]]
+ ["/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}.pdf" {...}]            ;; terminator \.
- ["/files/file-{name}-{version}.pdf"]] ;; terminator \-
+ ["/files/file-{name}-{version}.pdf" {...}]] ;; terminator \-
 ```
 
 ### Slash Free Routing
 
 ```clj
-[["broker.{customer}.{device}.{*data}"]
+[["broker.{customer}.{device}.{*data}" {...}]
- ["events.{target}.{type}"]]
+ ["events.{target}.{type}" {...}]]
 ```
 
 ### Generating routes