docs(api): adding docs to source code

Author: posva

src/errors.ts

@@ -34,17 +34,46 @@ export interface MatcherError extends RouterErrorBase {
   currentLocation?: MatcherLocation
 }
 
+/**
+ * Enumeration with all possible types for navigation failures. Can be passed to
+ * {@link isNavigationFailure} to check for specific failures.
+ */
 export enum NavigationFailureType {
+  /**
+   * An aborted navigation is a navigation that failed because a navigation
+   * guard returned `false` or called `next(false)`
+   */
   aborted = ErrorTypes.NAVIGATION_ABORTED,
+  /**
+   * A cancelled navigation is a navigation that failed because a more recent
+   * navigation finished started (not necessarily finished).
+   */
   cancelled = ErrorTypes.NAVIGATION_CANCELLED,
+  /**
+   * A duplicated navigation is a navigation that failed because it was
+   * initiated while already being at the exact same ___location.
+   */
   duplicated = ErrorTypes.NAVIGATION_DUPLICATED,
 }
+
+/**
+ * Extended Error that contains extra information regarding a failed navigation.
+ */
 export interface NavigationFailure extends RouterErrorBase {
+  /**
+   * Type of the navigation. One of {@link NavigationFailureType}
+   */
   type:
     | ErrorTypes.NAVIGATION_CANCELLED
     | ErrorTypes.NAVIGATION_ABORTED
     | ErrorTypes.NAVIGATION_DUPLICATED
+  /**
+   * Route ___location we were navigating from
+   */
   from: RouteLocationNormalized
+  /**
+   * Route ___location we were navigating to
+   */
   to: RouteLocationNormalized
 }
 

src/index.ts

@@ -34,7 +34,7 @@ export {
   RouteRecordRaw,
   NavigationGuard,
   NavigationGuardNext,
-  PostNavigationGuard,
+  NavigationHookAfter,
 } from './types'
 export {
   createRouter,

src/___location.ts

@@ -116,8 +116,8 @@ export function stripBase(pathname: string, base: string): string {
  * pointing towards the same {@link RouteRecord} and that all `params`, `query`
  * parameters and `hash` are the same
  *
- * @param a first {@link RouteLocation}
- * @param b second {@link RouteLocation}
+ * @param a - first {@link RouteLocation}
+ * @param b - second {@link RouteLocation}
  */
 export function isSameRouteLocation(
   stringifyQuery: (query: LocationQueryRaw) => string,
@@ -141,8 +141,8 @@ export function isSameRouteLocation(
  * Check if two `RouteRecords` are equal. Takes into account aliases: they are
  * considered equal to the `RouteRecord` they are aliasing.
  *
- * @param a first {@link RouteRecord}
- * @param b second {@link RouteRecord}
+ * @param a - first {@link RouteRecord}
+ * @param b - second {@link RouteRecord}
  */
 export function isSameRouteRecord(a: RouteRecord, b: RouteRecord): boolean {
   // since the original record has an undefined value for aliasOf

src/matcher/index.ts

@@ -379,7 +379,7 @@ function isAliasRecord(record: RouteRecordMatcher | undefined): boolean {
 /**
  * Merge meta fields of an array of records
  *
- * @param matched array of matched records
+ * @param matched - array of matched records
  */
 function mergeMetaFields(matched: MatcherLocation['matched']) {
   return matched.reduce(

src/matcher/pathParserRanker.ts

@@ -44,6 +44,9 @@ export interface PathParser {
   stringify(params: PathParams): string
 }
 
+/**
+ * @internal
+ */
 export interface _PathParserOptions {
   /**
    * Makes the RegExp case sensitive. Defaults to false
@@ -54,11 +57,12 @@ export interface _PathParserOptions {
    */
   strict?: boolean
   /**
-   * Should the RegExp match from the beginning by prepending a ^. Defaults to true
+   * Should the RegExp match from the beginning by prepending a `^` to it. Defaults to true
+   * @internal
    */
   start?: boolean
   /**
-   * Should the RegExp match until the end by appending a $. Defaults to true
+   * Should the RegExp match until the end by appending a `$` to it. Defaults to true
    */
   end?: boolean
 }

src/matcher/types.ts

@@ -8,6 +8,9 @@ import {
 import { ComponentPublicInstance } from 'vue'
 
 // normalize component/components into components and make every property always present
+/**
+ * Normalized version of a {@link RouteRecord | Route Record}
+ */
 export interface RouteRecordNormalized {
   /**
    * {@inheritDoc _RouteRecordBase.path}
@@ -77,4 +80,7 @@ export interface RouteRecordNormalized {
   aliasOf: RouteRecordNormalized | undefined
 }
 
+/**
+ * {@inheritDoc RouteRecordNormalized}
+ */
 export type RouteRecord = RouteRecordNormalized

src/navigationGuards.ts

@@ -41,9 +41,9 @@ function registerGuard(list: NavigationGuard[], guard: NavigationGuard) {
 }
 
 /**
- * Add a navigation guard that triggers whenever the current ___location is
- * left. Similarly to {@link beforeRouteLeave}, it has access to the
- * component instance as `this`.
+ * Add a navigation guard that triggers whenever the component for the current
+ * ___location is about to be left. Similar to {@link beforeRouteLeave} but can be
+ * used in any component. The guard is removed when the component is unmounted.
  *
  * @param leaveGuard - {@link NavigationGuard}
  */
@@ -68,9 +68,9 @@ export function onBeforeRouteLeave(leaveGuard: NavigationGuard) {
 }
 
 /**
- * Add a navigation guard that triggers whenever the current ___location is
- * updated. Similarly to {@link beforeRouteUpdate}, it has access to the
- * component instance as `this`.
+ * Add a navigation guard that triggers whenever the current ___location is about
+ * to be updated. Similar to {@link beforeRouteUpdate} but can be used in any
+ * component. The guard is removed when the component is unmounted.
  *
  * @param updateGuard - {@link NavigationGuard}
  */