Typedefs

Typal is a package to manage JSDoc typedefs from a separate types.xml file (or files). They can then be placed into JavaScript, used to generate Google Closure Compiler externs and embedded into documentation with Documentary. When placed in JS, one of the advantages is that it allows to expand function parameters' properties, so that they are better visible from the IDE:

The main use of Typal is together with Documentary to insert tables with types' descriptions.

On This Page

• On This Page
• README placement
  • SetHeaders
  • RightsConfig
  • StaticConfig

README placement

To place a type definition as a table into a README file, the TYPEDEF marker can be used, where the first argument is the path to the xml file containing definitions, and the second one is the name of the type to embed. Moreover, links to the type descriptions will be created in the table of contents using the TOC Titles, but to prevent this, the noToc attribute should be set for a type.

Show Types.Xml

<types>
  <import name="ServerResponse" from="http"
    link="https://nodejs.org/api/http.html#http_class_http_serverresponse"
  />
  <type name="SetHeaders"
    type="(res: ServerResponse) => any"
    desc="Function to set custom headers on response." />
  <type name="RightsConfig"
    type="{ location: string, rights: number }[]"
    desc="Configuration of read and write access rights." />
  <type name="StaticConfig" desc="Options to setup `koa-static`.">
    <prop string name="root">
      Root directory string.
    </prop>
    <prop number name="maxage" default="0">
      Browser cache max-age in milliseconds.
    </prop>
    <prop boolean name="hidden" default="false">
      Allow transfer of hidden files.
    </prop>
    <prop string name="index" default="index.html">
      Default file name.
    </prop>
    <prop opt type="SetHeaders" name="setHeaders">
      Function to set custom headers on response.
    </prop>
    <prop opt type="Promise.<RightsConfig>" name="rightsPromise">
      The promise which will be resolved with access rights to files.
    </prop>
  </type>
</types>

%TYPEDEF path/definitions.xml [TypeName]%

For example, using the previously defined StaticConfig type from types/static.xml file, Documentary will process the following markers:

%TYPEDEF types/static.xml ServerResponse%
%TYPEDEF types/static.xml SetHeaders%
%TYPEDEF types/static.xml StaticConfig%

or a single marker to include all types in order in which they appear in the xml file:

%TYPEDEF types/static.xml%

and embed resulting type definitions (with the imported type linked to the Node.JS documentation due to its link attribute):

import('http').ServerResponse http.ServerResponse: A writable stream that communicates data to the client. The second argument of the http.Server.on("request") event.

(res: ServerResponse) => any SetHeaders: Function to set custom headers on response.

{ location: string, rights: number } RightsConfig: Configuration of read and write access rights.

StaticConfig: Options to setup koa-static.

Name	Type	Description	Default
root*	string	Root directory string.	-
maxage	number	Browser cache max-age in milliseconds.	0
hidden	boolean	Allow transfer of hidden files.	false
index	string	Default file name.	index.html
setHeaders	SetHeaders	Function to set custom headers on response.	-
rightsPromise	Promise<RightsConfig>	The promise which will be resolved with access rights to files.	-

Documentary wil scan each source file of the documentation first to build a map of all types. Whenever a property appears to be of a known type, it will be automatically linked to the location where it was defined. It is also true for properties described as generic types, such as Promise<Type>. This makes it possible to define all types in one place, and then reference them in the API documentation. For the full list of supported types for linking, see Typal's documentation.

Read More about types in Documentary including advanced usage with the spread option.