From 2642d78cbc515eeb1e30732b179b225916460097 Mon Sep 17 00:00:00 2001
From: Asko Nõmm <asko@bien.ee>
Date: Sat, 2 Oct 2021 13:44:08 -0300
Subject: Add comments

---
 src/ruuter/core.clj | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/ruuter/core.clj b/src/ruuter/core.clj
index db079c2..1cf96cb 100644
--- a/src/ruuter/core.clj
+++ b/src/ruuter/core.clj
@@ -5,6 +5,8 @@
 
 
 (defn- path->regex-path
+  "Takes in a raw route `path` and turns it into a regex pattern to
+  match against the request URI."
   [path]
   (if (= "/" path)
     path
@@ -17,6 +19,8 @@
 
 
 (defn- path+uri->path-params
+  "Takes a raw route `path` and the actual request `uri`, which it then
+  turns into a map of k:v, if any parameters were used in the `path`."
   [path uri]
   (if (= "/" path)
     {}
@@ -30,6 +34,9 @@
 
 
 (defn- match-route
+  "For a collection of `route`, will attempt to find one that matches
+  the given `uri` and `request-method`. If none is matched, `nil` will
+  be returned instead."
   [routes uri request-method]
   (->> routes
        (filter #(not (= :not-found (:path %))))
@@ -40,6 +47,14 @@
 
 
 (defn- route+req->response
+  "Given the current route and the current HTTP request, it will
+   attempt to return a response, either directly if it's a map or
+   indirectly if it's a function. In case of a function, it will also
+   pass along the request map with added-in params that were parsed
+   from the route path.
+
+   If the response is invalid, or does not exist, a error message with
+   status code 404 will be returned instead."
   [{:keys [path response]} {:keys [uri] :as req}]
   (cond
     ; responses are maps, so there's no reason they can't be
@@ -61,6 +76,13 @@
 
 
 (defn- router
+  "For a given collection of `routes` and the current HTTP request as
+  `req`, will attempt to match a route with the HTTP request, which it
+  will then try to return a response for.
+
+  If no route matched for a given HTTP request it will try to find a
+  route with `:not-found` as its `:path` instead, and return the response
+  for that."
   [routes {:keys [uri request-method] :as req}]
   (if-let [route (match-route routes uri request-method)]
     (route+req->response route req)
@@ -70,6 +92,10 @@
 
 
 (defn route!
+  "Starts an HTTP server which will then try to find a matching route for
+  each request from within the given collection of `routes`. Takes an
+  optional `opts` map, which corresponds directly to HTTP-Kit's config,
+  allowing you to specify things like `{:port 8080}` and so on."
   ([routes]
    (route! routes {:port 9600}))
   ([routes opts]
-- 
cgit v1.2.3