docs: ✏️ Fix broken links in docs, improved types documentations, bet…

…ter types constraints This does not affect the behavior of the package. Closes: #128, #115
GerkinDev · May 3, 2020 · a54ce8c · a54ce8c
1 parent a804208
commit a54ce8c
Show file tree

Hide file tree

Showing 13 changed files with 56 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -18,9 +18,10 @@ E2E testing over Travis realized using
 
 [<img src="https://i1.wp.com/www.diogonunes.com/blog/wp-content/uploads/2016/07/browserstack-logo.png?resize=490%2C105" height="105.6" width="490.1" class="img-responsive"/>](https://www.browserstack.com/)
 
-[:point_right: Browse the documentation :books:](https://gerkindev.github.io/vuejs-datatable/)
 [:point_right: Check out the tutorials :books:](https://gerkindev.github.io/vuejs-datatable/tutorials/index.html)
 
+[:point_right: Browse the documentation :books:](https://gerkindev.github.io/vuejs-datatable/)
+
 ---
 
 ## Getting started
@@ -42,7 +43,7 @@ yarn add vuejs-datatable
 
 > The [*ESM*](https://medium.com/webpack/the-state-of-javascript-modules-4636d1774358) build (**E**cma**S**cript **M**odule) implies that your target browsers supports *ESM* **OR** you use a bundler, like [*webpack*](https://webpack.js.org/), [*rollup.js*](https://rollupjs.org/guide/en) or [*Parcel*](https://parceljs.org/).
 
-Import & register the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/DatatableFactory.html) in Vue:
+Import & register the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/classes/datatablefactory.html) in Vue:
 
 ```js
 import Vue from 'vue';
@@ -51,7 +52,7 @@ import { VuejsDatatableFactory } from 'vuejs-datatable';
 Vue.use( VuejsDatatableFactory );
 ```
 
-Check out [*how to customize table types*](#customize-the-datatable) to see some usage of the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/DatatableFactory.html) and the possible reasons not to use the default instance exported as `VuejsDatatableFactory`.
+Check out [*how to customize table types*](#customize-the-datatable) to see some usage of the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/classes/datatablefactory.html) and the possible reasons not to use the default instance exported as `VuejsDatatableFactory`.
 
 #### Use the IIFE build
 
@@ -68,7 +69,7 @@ In your HTML, load the *IIFE* build directly, if possible right before the closi
 </body>
 ```
 
-The *IIFE* build exposes the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/DatatableFactory.html) as the global `VuejsDatatable`. Check out [*how to customize table types*](#customize-the-datatable) to see some usage of the `DatatableFactory`.
+The *IIFE* build exposes the [*DatatableFactory*](https://gerkindev.github.io/vuejs-datatable/classes/datatablefactory.html) as the global `VuejsDatatable`. Check out [*how to customize table types*](https://gerkindev.github.io/vuejs-datatable/tutorials/customize/custom-theme/index.html) to see some usage of the `DatatableFactory`.
 
 ### Use the component
 
@@ -116,7 +117,7 @@ new Vue({
 
 ### Customize the datatable
 
-The DatatableFactory exposes several methods to allow you to add or modify other `datatable`-like components, with [custom styles](https://gerkindev.github.io/vuejs-datatable/tutorial-custom-theme.html) or [behavior](https://gerkindev.github.io/vuejs-datatable/tutorial-ajax-handler.html).
+The DatatableFactory exposes several methods to allow you to add or modify other `datatable`-like components, with [custom styles](https://gerkindev.github.io/vuejs-datatable/tutorials/customize/custom-theme/index.html) or [behavior](https://gerkindev.github.io/vuejs-datatable/tutorials/ajax/ajax-handler.html).
 
 ```js
 VuejsDatatable

diff --git a/src/classes/handlers/default-handler.ts b/src/classes/handlers/default-handler.ts
@@ -42,7 +42,7 @@ export class DefaultHandler<TRow extends {}> implements IHandler<TRow, TRow[], T
 	/**
 	 * Sort the given rows depending on a specific column & sort order.
 	 *
-	 * @param filteredData - Data outputed from [[Handler.filterHandler]].
+	 * @param filteredData - Data outputed from [[filterHandler]].
 	 * @param sortColumn   - The column used for sorting.
 	 * @param sortDir      - The direction of the sort.
 	 * @returns the sorted rows.
@@ -73,7 +73,7 @@ export class DefaultHandler<TRow extends {}> implements IHandler<TRow, TRow[], T
 	/**
 	 * Split the rows list to display the requested page index.
 	 *
-	 * @param sortedData - Data outputed from [[Handler.sortHandler]].
+	 * @param sortedData - Data outputed from [[sortHandler]].
 	 * @param perPage    - The total number of items per page.
 	 * @param pageNumber - The index of the page to display.
 	 * @returns the requested page's rows.

diff --git a/src/classes/handlers/i-handler.ts b/src/classes/handlers/i-handler.ts
@@ -17,13 +17,13 @@ export interface IDisplayHandlerResult<TRow extends {}> {
 }
 
 export interface IDisplayHandlerParam<TRow extends {}, TSource, TFiltered, TSorted, TPaged> {
-	/** The original [[Datatable.data]] property of the datatable. */
+	/** The original [[VueDatatable.data]] property of the datatable. */
 	source: TRow[] | TSource;
-	/** The return value of [[Handler.filterHandler]]. */
+	/** The return value of [[IHandler.filterHandler]]. */
 	filtered: TRow[] | TFiltered;
-	/** The return value of [[Handler.sortHandler]]. */
+	/** The return value of [[IHandler.sortHandler]]. */
 	sorted: TRow[] | TSorted;
-	/** The return value of [[Handler.paginateHandler]]. */
+	/** The return value of [[IHandler.paginateHandler]]. */
 	paged: TRow[] | TPaged;
 }
 
@@ -44,12 +44,12 @@ export type TDisplayHandler<TRow, TSource = TRow[], TFiltered = TRow[], TSorted
  * @tutorial ajax-handler
  */
 export interface IHandler<TRow extends {}, TSource = TRow[], TFiltered = TRow[], TSorted = TRow[], TPaged = TRow[]> {
-	/** Filter the provided rows, checking if at least a cell contains one of the specified filters. It supports promises. Defaults to [[Handler.defaultFilterHandler]]. */
+	/** Filter the provided rows, checking if at least a cell contains one of the specified filters. It supports promises. Defaults to [[DefaultHandler.filterHandler]]. */
 	filterHandler: TFilterHandler<TRow, TSource, TFiltered>;
-	/** Sort the given rows depending on a specific column & sort order. It suports promises. Defaults to [[Handler.defaultSortHandler]].  */
+	/** Sort the given rows depending on a specific column & sort order. It suports promises. Defaults to [[DefaultHandler.sortHandler]].  */
 	sortHandler: TSortHandler<TRow, TFiltered, TSorted>;
-	/** Split the rows list to display the requested page index. It supports promises. Defaults to [[Handler.defaultPaginateHandler]]. */
+	/** Split the rows list to display the requested page index. It supports promises. Defaults to [[DefaultHandler.paginateHandler]]. */
 	paginateHandler: TPaginateHandler<TRow, TSorted, TPaged>;
-	/** Handler to post-process the paginated data, and determine which data to actually display. It supports promises. Defaults to [[Handler.defaultDisplayHandler]]. */
+	/** Handler to post-process the paginated data, and determine which data to actually display. It supports promises. Defaults to [[DefaultHandler.displayHandler]]. */
 	displayHandler: TDisplayHandler<TRow, TSource, TFiltered, TSorted, TPaged>;
 }
diff --git a/src/components/mixins/table-type-consumer-factory.ts b/src/components/mixins/table-type-consumer-factory.ts
@@ -2,10 +2,15 @@ import { Component, Provide, Vue } from 'vue-property-decorator';
 
 import { TableType } from '../../classes';
 
+/**
+ * This interface describes a component from which the [[tableType]] can be accessed.
+ */
 export interface ITableTypeConsumer extends Vue {
+	/** Property containing the TableType used by this component. */
 	readonly tableType: TableType<any>;
 }
 
+/** @ignore */
 export const tableTypeConsumerFactory = ( tableType: TableType<any> ): typeof Vue & ( new() => ITableTypeConsumer ) => {
 	/**
 	 * This mixin provide a [[TableType]] to inner components, which allow them to access [[Settings]] (through [[TableType.setting]])

diff --git a/src/components/vue-datatable-header/vue-datatable-header.ts b/src/components/vue-datatable-header/vue-datatable-header.ts
@@ -26,7 +26,7 @@ export class VueDatatableHeader<TRow extends {}> extends Vue {
 	@Prop( { type: Object, required: true } ) private readonly column!: Column<TRow>;
 
 	/**
-	 * The [[TableType]] instance provided through [[TableTypeConsumer.tableType]].
+	 * The [[TableType]] instance provided through [[ITableTypeConsumer.tableType]].
 	 *
 	 * @vue Inject `table-type`
 	 */

diff --git a/src/components/vue-datatable-pager/vue-datatable-pager-button/vue-datatable-pager-button.ts b/src/components/vue-datatable-pager/vue-datatable-pager-button/vue-datatable-pager-button.ts
@@ -32,7 +32,7 @@ export class VueDatatablePagerButton extends Vue {
 	@Prop( { type: Number } ) private readonly value!: number | null;
 
 	/**
-	 * The [[TableType]] instance provided through [[TableTypeConsumer.tableType]].
+	 * The [[TableType]] instance provided through [[ITableTypeConsumer.tableType]].
 	 *
 	 * @vue Inject `table-type`
 	 */

diff --git a/src/components/vue-datatable-pager/vue-datatable-pager.ts b/src/components/vue-datatable-pager/vue-datatable-pager.ts
@@ -1,6 +1,7 @@
 import { Component, Prop, Vue } from 'vue-property-decorator';
 
 import { EPagerType, namespaceEvent } from '../../utils';
+import { ITableTypeConsumer } from '../mixins/table-type-consumer-factory';
 import { VueDatatable } from '../vue-datatable/vue-datatable';
 import { TableType } from './../../classes';
 
@@ -16,7 +17,7 @@ import template from './vue-datatable-pager.html';
 		PagerButton: VueDatatablePagerButton,
 	},
 } )
-export class VueDatatablePager<TSub extends VueDatatablePager<TSub>> extends Vue {
+export class VueDatatablePager<TSub extends VueDatatablePager<TSub>> extends Vue implements ITableTypeConsumer {
 	/**
 	 * The id of the associated [[VueDatatable]].
 	 *
@@ -32,7 +33,7 @@ export class VueDatatablePager<TSub extends VueDatatablePager<TSub>> extends Vue
 	@Prop( { type: String, default: EPagerType.Long } ) public readonly type!: EPagerType;
 
 	/**
-	 * The number of pages visible on each side (only for [[EPageType.Abbreviated]])
+	 * The number of pages visible on each side (only for [[EPagerType.Abbreviated]])
 	 *
 	 * @vue-prop
 	 */
@@ -79,7 +80,7 @@ export class VueDatatablePager<TSub extends VueDatatablePager<TSub>> extends Vue
 		return this.tableType.setting( 'pager.icons.next' );
 	}
 
-	protected readonly tableType!: TableType<any>;
+	public readonly tableType!: TableType<any>;
 	public get identifier() {
 		return this.tableType.id + '-pager';
 	}

diff --git a/src/components/vue-datatable/vue-datatable.ts b/src/components/vue-datatable/vue-datatable.ts
@@ -6,6 +6,7 @@ import { Column, IColumnDefinition } from '../../classes/column';
 import { ESortDir, IDisplayHandlerParam, IDisplayHandlerResult } from '../../classes/handlers';
 import { classValType, ensurePromise, mergeClassVals, namespaceEvent, TClassVal, TMaybePromise } from '../../utils';
 import { VueDatatablePager } from '../vue-datatable-pager/vue-datatable-pager';
+import { ITableTypeConsumer } from '../mixins/table-type-consumer-factory';
 
 import template from './vue-datatable.html';
 
@@ -25,15 +26,18 @@ export interface ITableContentParam<TRow extends {}> {
 	rows: TRow[];
 	totalRowCount: number;
 }
-export type TDataFn<TRow extends {}> = ( ( search: IDataFnParams<TRow> ) => ITableContentParam<TRow> );
+export type TDataFn<TRow extends {}> = ( ( search: IDataFnParams<TRow> ) => TMaybePromise<ITableContentParam<TRow>> );
 export type TColumnsDefinition<TRow extends {}> = Array<IColumnDefinition<TRow>>;
 
+/**
+ * Defines a pagination range. It orders to display the interval [`from`, `to`] in a list of a total of `of` items.
+ */
 interface IPageRange {
-	/** Index of the first element of the page. 1-indexed */
+	/** Index of the first element of the pagination to display. 1-indexed */
 	from: number;
-	/** Index of the last element of the page. 1-indexed */
+	/** Index of the last element of the pagination to display. 1-indexed */
 	to: number;
-	/** The total number of items */
+	/** The total number of items in the list. */
 	of: number;
 }
 
@@ -55,7 +59,7 @@ interface IPageRange {
 @Component( {
 	...template,
 } )
-export class VueDatatable<TRow extends {}, TSub extends VueDatatable<TRow, TSub>> extends Vue {
+export class VueDatatable<TRow extends {}, TSub extends VueDatatable<TRow, TSub>> extends Vue implements ITableTypeConsumer {
 	/**
 	 * The name of the datatable. It should be unique per page.
 	 *
@@ -117,7 +121,7 @@ export class VueDatatable<TRow extends {}, TSub extends VueDatatable<TRow, TSub>
 	/** Total number of rows contained by this data table. */
 	public totalRows = 0;
 
-	/** The total number of pages in the associated [[datatable]]. */
+	/** The total number of pages in the datatable. */
 	private get totalPages(): number | null {
 		if ( this.totalRows <= 0 || this.perPage <= 0 ) {
 			return 0;
@@ -159,7 +163,8 @@ export class VueDatatable<TRow extends {}, TSub extends VueDatatable<TRow, TSub>
 			.join( ' ' );
 	}
 
-	protected readonly tableType!: TableType<any>;
+	public readonly tableType!: TableType<any>;
+
 	public get handler() {
 		return this.tableType.handler;
 	}
@@ -296,8 +301,8 @@ export class VueDatatable<TRow extends {}, TSub extends VueDatatable<TRow, TSub>
 
 	/**
 	 * Starts the watching of following properties: `filter`, `perPage`, `page`, `sortBy`, `sortDir`.
-	 * When a change is detected, the component runs [[datatable#processRows]].
-	 * Because the watch is immediate, [[datatable#processRows]] is run immediately when this method is called.
+	 * When a change is detected, the component runs [[processRows]].
+	 * Because the watch is immediate, [[processRows]] is run immediately when this method is called.
 	 *
 	 * @see datatable#processRows
 	 * @see https://vuejs.org/v2/api/#vm-watch

diff --git a/src/utils.ts b/src/utils.ts
@@ -1,7 +1,9 @@
 
 export type TMaybePromise<T> = T | Promise<T>;
 
+/** @ignore */
 const isPromise = <T>( value: any ): value is Promise<T> => value && typeof value.then === 'function';
+/** @ignore */
 export const ensurePromise = <T>( value: TMaybePromise<T> ): Promise<T> => {
 	if ( isPromise( value ) )  {
 		return value;
@@ -12,7 +14,9 @@ export const ensurePromise = <T>( value: TMaybePromise<T> ): Promise<T> => {
 
 export interface IDict<T> {[key: string]: T; }
 export type TClassVal = string | string[] | IDict<boolean>;
+/** @ignore */
 export const classValType: any[] = [ String, Array, Object ];
+/** @ignore */
 export const mergeClassVals = ( mainObj: TClassVal, ...objs: Array<TClassVal | null | undefined> ): string[] =>
 	Object.entries(
 		Object.assign(
@@ -34,7 +38,9 @@ const canonicalClassVals = ( classVal: TClassVal | null | undefined ): IDict<boo
 	return classVal || {};
 };
 
+/** @ignore */
 export const namespace = 'vue-datatable';
+/** @ignore */
 export const namespaceEvent = ( event: string ) => `${namespace}::${event}`;
 
 /**
@@ -57,6 +63,7 @@ export const enum EPagerType {
 	Long = 'long',
 }
 
+/** @ignore */
 export const valueToString = ( val: any ): string => {
 	if ( val === null || typeof val === 'undefined' ) {
 		return '';

diff --git a/tutorials/src/bundlers/index.md b/tutorials/src/bundlers/index.md
@@ -29,7 +29,7 @@ const Vue = require( 'vue' );
 import Vue from 'vue';
 ```
 
-Instead of targeting the right build in your code, configure your bundler to alias the `vue` module as your desired `vue` dist file. Check below for [how to alias `vue`](#alias-the-vue-module).
+Instead of targeting the right build in your code, configure your bundler to alias the `vue` module as your desired `vue` dist file. Check below for [how to alias `vue`](#alias-the-codevuecode-module).
 
 #### `You are using the runtime-only build of Vue where the template compiler is not available. Either pre-compile the templates into render functions, or use the compiler-included build.`
 

diff --git a/tutorials/src/custom-template/index.md b/tutorials/src/custom-template/index.md
@@ -4,7 +4,7 @@ This plugin is built to be as versatile as possible, and allow you to inject you
 
 ### Datatable
 
-> See the [Datatable API doc](../classes/vuedatatable.html)
+> See the [Datatable API doc](../../classes/vuedatatable.html)
 
 #### `footer` slot
 
@@ -15,8 +15,8 @@ This footer is displayed at the bottom of your data table.
 | Prop | Type   | Description |
 |------|--------|-------------|
 | `rows` | `TRow[]` | The list of rows currently displayed by the table. It only contains the current page. |
-| `columns` | [`Column[]`](../classes/column.html) | The columns of the table |
-| `pagination` | [`IPageRange`](../interfaces/ipagerange.html) | An object describing the current pagination status |
+| `columns` | [`Column[]`](../../classes/column.html) | The columns of the table |
+| `pagination` | [`IPageRange`](../../interfaces/ipagerange.html) | An object describing the current pagination status |
 
 ##### Example
 
@@ -40,7 +40,7 @@ This slot is used to render each rows. It completely overrides the default row r
 |------|--------|-------------|
 | `row` | `TRow` | The current row that it is appending to the table. |
 | `index` | `number` | The current index of the row in the displayed page. |
-| `columns` | `Column[]` | The [columns](../classes/column.html) of the table |
+| `columns` | `Column[]` | The [columns](../../classes/column.html) of the table |
 
 ##### Example
 

diff --git a/tutorials/src/custom-theme/index.md b/tutorials/src/custom-theme/index.md
@@ -1,6 +1,6 @@
 ## Introduction
 
-You can customize the appearance of your table by merging a [Settings Props object](../interfaces/isettingsproperties.html) in your [Table Type](../classes/tabletype.html), by using [TableType.mergeSettings](../classes/tabletype.html#mergesettings).
+You can customize the appearance of your table by merging a [Settings Props object](../../../interfaces/isettingsproperties.html) in your [Table Type](../../../classes/tabletype.html), by using [TableType.mergeSettings](../../../classes/tabletype.html#mergesettings).
 
 <div class="alert alert-info">
     <i class="fas fa-info-circle"></i>

diff --git a/typedoc.json b/typedoc.json
@@ -4,11 +4,13 @@
     "readme": "README.md",
     "exclude": [
         "./**/*.spec.*",
+        "./**/__mocks__/**/*",
         "./dist/**/*",
         "./ci/**/*",
         "./docs/**/*",
         "./tutorials/**/*"
     ],
+    "listInvalidSymbolLinks": true,
 
     "tutorials-map": "./tutorials/tutorials.json",
     "tutorials-directory": "./tutorials/dist"