Merge pull request #507 from metosin/feature/improve-frontend-docs

Improve parameter names and docstrings on reitit frontend functions

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,64 @@
                        (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 a URL for a route defined by name, with given path-params and query-params.
 
-(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)))
+  The URL is formatted using Reitit frontend history handler, so using it with
+  anchor element href will correctly trigger route change event.
 
-(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)))
+  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
+  ^{:see-also ["reitit.frontend.history/push-state"]}
+  push-state
+  "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.
+
+  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.
+
+  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
+  "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
+  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)))

modules/reitit-frontend/src/reitit/frontend/history.cljs

@@ -171,40 +171,73 @@
               (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 a URL for a route defined by name, with given path-params and query-params.
 
-(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)]
+  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]
+   (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
+  "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
+  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)]
+  "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
+  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))))