Guidelines for API reference docs

Packages documentation

Structure

A typical structure for a Frontity package includes the following sections

- Installation
- Settings
- How to use
- API Reference
  * Actions
  * State
  * Libraries

Check example

Table of Contents

To ease navigations through doc, especially in long documents, including a Table of Contents (TOC) section is recommended

This TOC can be automatically created with the script toc available in the repo.

This script receives as argument the relative path of the file where the Table of Contents should be created

 npm run toc -- docs-api/frontity-plugins/rest-api-head-tags.md

The target file should have the following comments to indicate the script where the generated TOC should be inserted

## Table of Contents

<!-- toc -->
<!-- tocstop -->

Check example

Method API Structure

A typical structure for a method include the following sections

• Syntax
• Arguments
• Return value
• Example

Check example

Syntax

Quick reference for syntax either in typescript ir pseudo-language

Example

(link: string) => object`

Example

actions.router.set = async (link: string, options: {
  method: "push" | "replace",
  state: object
}): Promise<void>;

Arguments

Arguments of function will be preferably documented using tables with a recommended maximum of 5 columns

Example

Name	Type	Required	Description
link	string	yes	The URL that will replace the current one. link is short for permalink. Examples:
options	object	no	Options object
options.method	string	-	The method used in the action. Possible values: "push" corresponds to window.history.pushState and "replace" to window.history.replaceState Default Value is "push"
options.state	object	-	An object that will be saved in window.history.state. This object is recovered when the user go back and forward using the browser buttons.

• Name field will describe the name of the field (real or symbolic)

  • If the name is symbolic (arguments of a function doesn't really have a name, their identified by position) it will be displayed with italic font
  • If the name is real (keys in an object) it will be displayed with normal font

• If the argument is required the Name will be in bold

• Type will show the type of data: string, object, array, function, boolean or any other type description that can make it more clear (array of numbers, React component, Promise, ...)

• Required yes or no to indicate if the field/argument/property is mandatory or not

• Description Purpose of the argument, content of the argument