From ac68f0f726b88ecfec31591ae7b9e9aa20161802 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Tue, 7 Sep 2021 14:38:42 +0300
Subject: [PATCH 1/2] Improve parameter names and docstrings on reitit frontend
 functions

---
 .../src/reitit/frontend/easy.cljs             | 78 +++++++++++++------
 .../src/reitit/frontend/history.cljs          | 77 ++++++++++++------
 2 files changed, 106 insertions(+), 49 deletions(-)

diff --git a/modules/reitit-frontend/src/reitit/frontend/easy.cljs b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
index 94a1789a..b3befcbd 100644
--- a/modules/reitit-frontend/src/reitit/frontend/easy.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
@@ -10,7 +10,8 @@
 ;; Differences:
 ;; This one automatically removes previous event listeners.
 
-(defn start!
+(defn ^{:see-also ["reitit.frontend.history/start!"]}
+  start!
   "This registers event listeners on HTML5 history and hashchange events.
 
   Automatically removes previous event listeners so it is safe to call this repeatedly, for example when using
@@ -39,28 +40,57 @@
                        (on-navigate m this))
     opts))
 
-(defn href
-  ([k]
-   (rfh/href @history k nil nil))
-  ([k params]
-   (rfh/href @history k params nil))
-  ([k params query]
-   (rfh/href @history k params query)))
+(defn
+  ^{:see-also ["reitit.frontend.history/href"]}
+  href
+  "Generate link href for the given route and parameters
 
-(defn push-state
-  "Sets the new route, leaving previous route in history."
-  ([k]
-   (rfh/push-state @history k nil nil))
-  ([k params]
-   (rfh/push-state @history k params nil))
-  ([k params query]
-   (rfh/push-state @history k params query)))
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first."
+  ([name]
+   (rfh/href @history name nil nil))
+  ([name path-params]
+   (rfh/href @history name path-params nil))
+  ([name path-params query-params]
+   (rfh/href @history name path-params query-params)))
 
-(defn replace-state
-  "Replaces current route. I.e. current route is not left on history."
-  ([k]
-   (rfh/replace-state @history k nil nil))
-  ([k params]
-   (rfh/replace-state @history k params nil))
-  ([k params query]
-   (rfh/replace-state @history k params query)))
+(defn
+  ^{:see-also ["reitit.frontend.history/push-state"]}
+  push-state
+  "Creates url using the given route and parameters, pushes those to
+  history stack with pushState and triggers on-navigate callback on the
+  history handler.
+
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first.
+
+  See also:
+  https://developer.mozilla.org/en-US/docs/Web/API/History/pushState"
+  ([name]
+   (rfh/push-state @history name nil nil))
+  ([name path-params]
+   (rfh/push-state @history name path-params nil))
+  ([name path-params query-params]
+   (rfh/push-state @history name path-params query-params)))
+
+(defn
+  ^{:see-also ["reitit.frontend.history/replace-state"]}
+  replace-state
+  "Creates url using the given route and parameters, replaces latest entry on
+  history stack with replaceState and triggers on-navigate callback on the
+  history handler.
+
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first.
+
+  See also:
+  https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState"
+  ([name]
+   (rfh/replace-state @history name nil nil))
+  ([name path-params]
+   (rfh/replace-state @history name path-params nil))
+  ([name path-params query-params]
+   (rfh/replace-state @history name path-params query-params)))
diff --git a/modules/reitit-frontend/src/reitit/frontend/history.cljs b/modules/reitit-frontend/src/reitit/frontend/history.cljs
index 84ec5141..53967af4 100644
--- a/modules/reitit-frontend/src/reitit/frontend/history.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/history.cljs
@@ -171,40 +171,67 @@
               (map->FragmentHistory opts)
               (map->Html5History opts))))))
 
-(defn stop! [history]
+(defn stop!
+  "Stops the given history handler, removing the event handlers."
+  [history]
   (if history
     (-stop history)))
 
 (defn href
-  ([history k]
-   (href history k nil))
-  ([history k params]
-   (href history k params nil))
-  ([history k params query]
-   (let [match (rf/match-by-name! (:router history) k params)]
-     (-href history (reitit/match->path match query)))))
+  "Generate link href for the given route and parameters
 
-(defn push-state
-  "Sets the new route, leaving previous route in history."
-  ([history k]
-   (push-state history k nil nil))
-  ([history k params]
-   (push-state history k params nil))
-  ([history k params query]
-   (let [match (rf/match-by-name! (:router history) k params)
-         path (reitit/match->path match query)]
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first."
+  ([history name]
+   (href history name nil))
+  ([history name path-params]
+   (href history name path-params nil))
+  ([history name path-params query-params]
+   (let [match (rf/match-by-name! (:router history) name path-params)]
+     (-href history (reitit/match->path match query-params)))))
+
+(defn
+  ^{:see-also ["reitit.core/match->path"]}
+  push-state
+  "Creates url using the given route and parameters, pushes those to
+  history stack with pushState and triggers on-navigate callback on the
+  history handler.
+
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first.
+
+  See also:
+  https://developer.mozilla.org/en-US/docs/Web/API/History/pushState"
+  ([history name]
+   (push-state history name nil nil))
+  ([history name path-params]
+   (push-state history name path-params nil))
+  ([history name path-params query-params]
+   (let [match (rf/match-by-name! (:router history) name path-params)
+         path (reitit/match->path match query-params)]
      ;; pushState and replaceState don't trigger popstate event so call on-navigate manually
      (.pushState js/window.history nil "" (-href history path))
      (-on-navigate history path))))
 
 (defn replace-state
-  "Replaces current route. I.e. current route is not left on history."
-  ([history k]
-   (replace-state history k nil nil))
-  ([history k params]
-   (replace-state history k params nil))
-  ([history k params query]
-   (let [match (rf/match-by-name! (:router history) k params)
-         path (reitit/match->path match query)]
+  "Creates url using the given route and parameters, replaces latest entry on
+  history stack with replaceState and triggers on-navigate callback on the
+  history handler.
+
+  Note: currently collections in query-parameters are encoded as field-value
+  pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
+  differently, convert the collections to strings first.
+
+  See also:
+  https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState"
+  ([history name]
+   (replace-state history name nil nil))
+  ([history name path-params]
+   (replace-state history name path-params nil))
+  ([history name path-params query-params]
+   (let [match (rf/match-by-name! (:router history) name path-params)
+         path (reitit/match->path match query-params)]
      (.replaceState js/window.history nil "" (-href history path))
      (-on-navigate history path))))

From 9eded42ba1f951e9965e873b42f97cb6458c965a Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Wed, 3 Nov 2021 12:52:45 +0200
Subject: [PATCH 2/2] Improve frontend docstrings

---
 .../src/reitit/frontend/easy.cljs             | 23 ++++++++++++-------
 .../src/reitit/frontend/history.cljs          | 22 +++++++++++-------
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/modules/reitit-frontend/src/reitit/frontend/easy.cljs b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
index b3befcbd..5e329e38 100644
--- a/modules/reitit-frontend/src/reitit/frontend/easy.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/easy.cljs
@@ -43,7 +43,10 @@
 (defn
   ^{:see-also ["reitit.frontend.history/href"]}
   href
-  "Generate link href for the given route and parameters
+  "Generate a URL for a route defined by name, with given path-params and query-params.
+
+  The URL is formatted using Reitit frontend history handler, so using it with
+  anchor element href will correctly trigger route change event.
 
   Note: currently collections in query-parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
@@ -58,11 +61,13 @@
 (defn
   ^{:see-also ["reitit.frontend.history/push-state"]}
   push-state
-  "Creates url using the given route and parameters, pushes those to
-  history stack with pushState and triggers on-navigate callback on the
-  history handler.
+  "Updates the browser location and pushes new entry to the history stack using
+  URL built from a route defined by name, with given path-params and
+  query-params.
 
-  Note: currently collections in query-parameters are encoded as field-value
+  Will also trigger on-navigate callback on Reitit frontend History handler.
+
+  Note: currently collections in query parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
   differently, convert the collections to strings first.
 
@@ -78,9 +83,11 @@
 (defn
   ^{:see-also ["reitit.frontend.history/replace-state"]}
   replace-state
-  "Creates url using the given route and parameters, replaces latest entry on
-  history stack with replaceState and triggers on-navigate callback on the
-  history handler.
+  "Updates the browser location and replaces latest entry in the history stack
+  using URL built from a route defined by name, with given path-params and
+  query-params.
+
+  Will also trigger on-navigate callback on Reitit frontend History handler.
 
   Note: currently collections in query-parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
diff --git a/modules/reitit-frontend/src/reitit/frontend/history.cljs b/modules/reitit-frontend/src/reitit/frontend/history.cljs
index 53967af4..f135d7bc 100644
--- a/modules/reitit-frontend/src/reitit/frontend/history.cljs
+++ b/modules/reitit-frontend/src/reitit/frontend/history.cljs
@@ -178,9 +178,12 @@
     (-stop history)))
 
 (defn href
-  "Generate link href for the given route and parameters
+  "Generate a URL for a route defined by name, with given path-params and query-params.
 
-  Note: currently collections in query-parameters are encoded as field-value
+  The URL is formatted using Reitit frontend history handler, so using it with
+  anchor element href will correctly trigger route change event.
+
+  Note: currently collections in query parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
   differently, convert the collections to strings first."
   ([history name]
@@ -194,9 +197,10 @@
 (defn
   ^{:see-also ["reitit.core/match->path"]}
   push-state
-  "Creates url using the given route and parameters, pushes those to
-  history stack with pushState and triggers on-navigate callback on the
-  history handler.
+  "Updates the browser URL and pushes new entry to the history stack using
+  a route defined by name, with given path-params and query-params.
+
+  Will also trigger on-navigate callback on Reitit frontend History handler.
 
   Note: currently collections in query-parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them
@@ -216,9 +220,11 @@
      (-on-navigate history path))))
 
 (defn replace-state
-  "Creates url using the given route and parameters, replaces latest entry on
-  history stack with replaceState and triggers on-navigate callback on the
-  history handler.
+  "Updates the browser location and replaces latest entry in the history stack
+  using URL built from a route defined by name, with given path-params and
+  query-params.
+
+  Will also trigger on-navigate callback on Reitit frontend History handler.
 
   Note: currently collections in query-parameters are encoded as field-value
   pairs separated by &, i.e. \"?a=1&a=2\", if you want to encode them