docs(api): add history functions

Author: posva

docs/api/index.md

@@ -142,3 +142,94 @@ When a `<router-view>` has a `name`, it will render the component with the corre
 ### route
 
 - type: `RouteLocationNormalizedLoaded`. A route ___location that has all of its component resolved (if any was lazy loaded) so it can be displayed.
+
+## createRouter
+
+Creates a Router instance that can be used by a Vue app.
+
+**Signature:**
+
+```typescript
+export declare function createRouter(options: RouterOptions): Router
+```
+
+### Parameters
+
+| Parameter | Type                                                    | Description                      |
+| --------- | ------------------------------------------------------- | -------------------------------- |
+| options   | [`RouterOptions`](./vue-router-interface#routeroptions) | Options to initialize the router |
+
+## createWebHistory
+
+Creates an HTML5 history. Most common history for single page applications. The application must be served through the http protocol.
+
+**Signature:**
+
+```typescript
+export declare function createWebHistory(base?: string): RouterHistory
+```
+
+### Parameters
+
+| Parameter | Type     | Description                                                                                                           |
+| --------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| base      | `string` | optional base to provide. Useful when the application is hosted inside of a folder like `https://example.com/folder/` |
+
+### Examples
+
+```js
+createWebHistory() // No base, the app is hosted at the root of the ___domain
+createWebHistory('/folder/') // gives a url of `https://example.com/folder/`
+```
+
+## createWebHashHistory
+
+Creates a hash history. Useful for web applications with no host (e.g. `file://`) or when configuring a server to handle any URL.
+
+**Signature:**
+
+```typescript
+export declare function createWebHashHistory(base?: string): RouterHistory
+```
+
+### Parameters
+
+| Parameter | Type     | Description                                                                                                                                         |
+| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| base      | `string` | optional base to provide. Defaults to `___location.pathname` or `/` if at root. If there is a `base` tag in the `head`, its value will be **ignored**. |
+
+### Examples
+
+```js
+// at https://example.com/folder
+createWebHashHistory() // gives a url of `https://example.com/folder#`
+createWebHashHistory('/folder/') // gives a url of `https://example.com/folder/#`
+// if the `#` is provided in the base, it won't be added by `createWebHashHistory`
+createWebHashHistory('/folder/#/app/') // gives a url of `https://example.com/folder/#/app/`
+// you should avoid doing this because it changes the original url and breaks copying urls
+createWebHashHistory('/other-folder/') // gives a url of `https://example.com/other-folder/#`
+
+// at file:///usr/etc/folder/index.html
+// for locations with no `host`, the base is ignored
+createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/index.html#`
+```
+
+## createMemoryHistory
+
+Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special ___location that is nowhere. It's up to the user to replace that ___location with the starter ___location.
+
+**Signature:**
+
+```typescript
+export declare function createMemoryHistory(base?: string): RouterHistory
+```
+
+### Parameters
+
+| Parameter | Type   | Description                               |
+| --------- | ------ | ----------------------------------------- |
+| base      | string | Base applied to all urls, defaults to '/' |
+
+### Returns
+
+a history object that can be passed to the router constructor

docs/api/vue-router-function.md

@@ -1,72 +1,5 @@
 # Function
 
-## createMemoryHistory
-
-Creates a in-memory based history. The main purpose of this history is to handle SSR. It starts in a special ___location that is nowhere. It's up to the user to replace that ___location with the starter ___location.
-
-**Signature:**
-```typescript
-export declare function createMemoryHistory(base?: string): RouterHistory;
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| base | string | Base applied to all urls, defaults to '/' |
-
-### Returns
-
- a history object that can be passed to the router constructor
-
-## createRouter
-
-Create a Router instance that can be used on a Vue app.
-
-**Signature:**
-```typescript
-export declare function createRouter(options: RouterOptions): Router;
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| options | RouterOptions | [RouterOptions](./vue-router-interface#routeroptions) |
-
-## createWebHashHistory
-
-Creates a hash history.
-
-**Signature:**
-```typescript
-export declare function createWebHashHistory(base?: string): RouterHistory;
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| base | string | optional base to provide. Defaults to `___location.pathname` or `/` if at root. If there is a `base` tag in the `head`, its value will be **ignored**. |
-
-### Examples
-
-
-```js
-// at https://example.com/folder
-createWebHashHistory() // gives a url of `https://example.com/folder#`
-createWebHashHistory('/folder/') // gives a url of `https://example.com/folder/#`
-// if the `#` is provided in the base, it won't be added by `createWebHashHistory`
-createWebHashHistory('/folder/#/app/') // gives a url of `https://example.com/folder/#/app/`
-// you should avoid doing this because it changes the original url and breaks copying urls
-createWebHashHistory('/other-folder/') // gives a url of `https://example.com/other-folder/#`
-
-// at file:///usr/etc/folder/index.html
-// for locations with no `host`, the base is ignored
-createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/index.html#`
-```
-
-
 ## createWebHistory
 
 ## isNavigationFailure
@@ -75,75 +8,78 @@ createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/in
 
 ## onBeforeRouteLeave
 
-Add a navigation guard that triggers whenever the component for the current ___location is about to be left. Similar to  but can be used in any component. The guard is removed when the component is unmounted.
+Add a navigation guard that triggers whenever the component for the current ___location is about to be left. Similar to but can be used in any component. The guard is removed when the component is unmounted.
 
 **Signature:**
+
 ```typescript
-export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void;
+export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void
 ```
 
 ### Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
+| Parameter  | Type            | Description                                               |
+| ---------- | --------------- | --------------------------------------------------------- |
 | leaveGuard | NavigationGuard | [NavigationGuard](./vue-router-interface#navigationguard) |
 
 ## onBeforeRouteUpdate
 
-Add a navigation guard that triggers whenever the current ___location is about to be updated. Similar to  but can be used in any component. The guard is removed when the component is unmounted.
+Add a navigation guard that triggers whenever the current ___location is about to be updated. Similar to but can be used in any component. The guard is removed when the component is unmounted.
 
 **Signature:**
+
 ```typescript
-export declare function onBeforeRouteUpdate(updateGuard: NavigationGuard): void;
+export declare function onBeforeRouteUpdate(updateGuard: NavigationGuard): void
 ```
 
 ### Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
+| Parameter   | Type            | Description                                               |
+| ----------- | --------------- | --------------------------------------------------------- |
 | updateGuard | NavigationGuard | [NavigationGuard](./vue-router-interface#navigationguard) |
 
 ## parseQuery
 
 Transforms a queryString into a [LocationQuery](./vue-router-typealias#locationquery) object. Accept both, a version with the leading `?` and without Should work as URLSearchParams
 
 **Signature:**
+
 ```typescript
-export declare function parseQuery(search: string): LocationQuery;
+export declare function parseQuery(search: string): LocationQuery
 ```
 
 ### Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| search | string | search string to parse |
+| Parameter | Type   | Description            |
+| --------- | ------ | ---------------------- |
+| search    | string | search string to parse |
 
 ### Returns
 
- a query object
+a query object
 
 ## stringifyQuery
 
 Stringifies a [LocationQueryRaw](./vue-router-typealias#locationqueryraw) object. Like `URLSearchParams`, it doesn't prepend a `?`
 
 **Signature:**
+
 ```typescript
-export declare function stringifyQuery(query: LocationQueryRaw): string;
+export declare function stringifyQuery(query: LocationQueryRaw): string
 ```
 
 ### Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| query | LocationQueryRaw | query object to stringify |
+| Parameter | Type             | Description               |
+| --------- | ---------------- | ------------------------- |
+| query     | LocationQueryRaw | query object to stringify |
 
 ### Returns
 
- string version of the query without the leading `?`
+string version of the query without the leading `?`
 
 ## useLink
 
 ## useRoute
 
 ## useRouter
-

src/history/hash.ts

@@ -3,7 +3,8 @@ import { createWebHistory } from './html5'
 import { warn } from '../warning'
 
 /**
- * Creates a hash history.
+ * Creates a hash history. Useful for web applications with no host (e.g.
+ * `file://`) or when configuring a server to handle any URL.
  *
  * @param base - optional base to provide. Defaults to `___location.pathname` or
  * `/` if at root. If there is a `base` tag in the `head`, its value will be

src/history/html5.ts

@@ -271,6 +271,11 @@ function useHistoryStateNavigation(base: string) {
   }
 }
 
+/**
+ * Creates an HTML5 history. Most common history for single page applications.
+ *
+ * @param base
+ */
 export function createWebHistory(base?: string): RouterHistory {
   base = normalizeBase(base)
 

src/router.ts

@@ -318,7 +318,7 @@ export interface Router {
 }
 
 /**
- * Create a Router instance that can be used on a Vue app.
+ * Creates a Router instance that can be used by a Vue app.
  *
  * @param options - {@link RouterOptions}
  */