Type (Deprecated)

This a pre-Typdef rule. It's better to use Typedefs for type definitions, however this rule can be used for simple use cases. It also allows to embed examples on a separate row.

Often, it is required to document a type of an object, which methods can use. To display the information about type's properties in a table, the TYPE macro can be used. It allows to show all possible properties that an object can contain, show which ones are required, give examples and link them in the table of contents (disabled by default).

Its signature is as follows:

%TYPE addToToc(true|false)
<p name="propertyName" type="propertyType" required>
  <d>Property Description.</d>
  <d>Property Example.</d>
</p>
%

For example,

%TYPE
<p name="text" type="string" required>
  <d>Display text. Required.</d>
  <e>

```js
const q = {
  text: 'What is your name',
}
```
  </e>
</p>
<p name="validation" type="(async) function">
  <d>A function which needs to throw an error if validation does not pass.</d>
  <e>

```js
const q = {
  text: 'What is your name',
  validate(v) {
    if (!v.length) throw new Error('Name is required.')
  },
}
```
  </e>
</p>
%

will display the following table:

Property	Type	Description	Example
text*	string	Display text. Required.	const q = { text: 'What is your name', }
validation	(async) function	A function which needs to throw an error if validation does not pass.	const q = { text: 'What is your name', validate(v) { if (!v.length) throw new Error('Name is required.') }, }

When required to use the markdown syntax in tables (such as __, links, etc), an extra space should be left after the d or e tags like so:

%TYPE true
<p name="skipLevelOne" type="boolean">
  <d>

Start the table of contents from level 2, i.e., excluding the `#` title.</d>
</p>
%

Otherwise, the content will not be processed by GitHub. However, it will add an extra margin to the content of the cell as it will be transformed into a paragraph.

Dedicated Example Row

Because examples occupy a lot of space which causes table squeezing on GitHub and scrolling on NPM, Documentary allows to dedicate a special row to an example. It can be achieved by adding a row attribute to the e element, like so:

%TYPE
<p name="headers" type="object">
  <d>Incoming headers returned by the server.</d>
  <e row>

```json
{
  "server": "GitHub.com",
  "content-type": "application/json",
  "content-length": "2",
  "connection": "close",
  "status": "200 OK"
}
```
  </e>
</p>
%

In addition, any properties which do not contain examples will not have an example column at all.

Property	Type	Description	Example
body	string|object|Buffer	The return from the server.
headers	object	Incoming headers returned by the server.
{ "server": "GitHub.com", "content-type": "application/json", "content-length": "2", "connection": "close", "status": "200 OK" }
statusCode	number	The status code returned by the server.	200

Finally, when no examples which are not rows are given, there will be no Example heading.

%TYPE
<p name="data" type="object">
  <d>Optional data to send to the server with the request.</d>
  <e row>

```js
{
  name: 'test',
}
```
  </e>
</p>
<p name="method" type="string">
  <d>What HTTP method to use to send data (only works when <code>data</code> is set).</d>
</p>
%

Property	Type	Description
data	object	Optional data to send to the server with the request.
{ name: 'test', }
method	string	What HTTP method to use to send data (only works when data is set).