docs: document history

diff --git a/src/history/common.ts b/src/history/common.ts
index dcb8723193b8c54eb85df5791aebcb5535f47e4d..314f006f90841c75fe2f0aa419b33a07453c0efa 100644 (file)
--- a/src/history/common.ts
+++ b/src/history/common.ts
@@ -46,7 +46,9 @@ export interface NavigationCallback {
   ): void
 }
 
-// starting point for abstract history
+/**
+ * Starting location for Histories
+ */
 const START_PATH = ''
 export const START: HistoryLocationNormalized = {
   fullPath: START_PATH,
@@ -54,19 +56,81 @@ export const START: HistoryLocationNormalized = {
 
 export type ValueContainer<T> = { value: T }
 
+/**
+ * Interface implemented by History implementations that can be passed to the
+ * router as {@link Router.history}
+ *
+ * @alpha
+ */
 export interface RouterHistory {
+  /**
+   * Base path that is prepended to every url. This allows hosting an SPA at a
+   * subfolder of a domain like `example.com/subfolder` by having a `base` of
+   * `/subfolder`
+   */
   readonly base: string
+  /**
+   * Current History location
+   */
   readonly location: HistoryLocationNormalized
+  /**
+   * Current History state
+   */
   readonly state: HistoryState
   // readonly location: ValueContainer<HistoryLocationNormalized>
 
+  /**
+   * Navigates to a location. In the case of an HTML5 History implementation,
+   * this will call `history.pushState` to effectively change the URL.
+   *
+   * @param to - location to push
+   * @param data - optional {@link HistoryState} to be associated with the
+   * navigation entry
+   */
   push(to: RawHistoryLocation, data?: HistoryState): void
+  /**
+   * Same as {@link RouterHistory.push} but performs a `history.replaceState`
+   * instead of `history.pushState`
+   *
+   * @param to - location to set
+   * @param data - optional {@link HistoryState} to be associated with the
+   * navigation entry
+   */
   replace(to: RawHistoryLocation, data?: HistoryState): void
 
+  /**
+   * Goes back in history
+   *
+   * @param triggerListeners - whether this should trigger listeners attached to
+   * the history
+   */
   back(triggerListeners?: boolean): void
+  /**
+   * Goes forward in history
+   *
+   * @param triggerListeners - whether this should trigger listeners attached to
+   * the history
+   */
   forward(triggerListeners?: boolean): void
+  /**
+   * Traverses history in a given direction
+   *
+   * @param distance - distance to travel. If distance is \< 0, it will go back,
+   * if it's \> 0, it will go forward
+   * @param triggerListeners - whether this should trigger listeners attached to
+   * the history
+   */
   go(distance: number, triggerListeners?: boolean): void
 
+  /**
+   * Attach a listener to the History implementation that is triggered when the
+   * navigation is triggered from outside (like the Browser back and forward
+   * buttons) or when passing `true` to {@link RouterHistory.back} and
+   * {@link RouterHistory.forward}
+   *
+   * @param callback - listener to attach
+   * @returns a callback to remove the listener
+   */
   listen(callback: NavigationCallback): () => void
   destroy(): void
 }