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] 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