API Reference Docs Structure¶

The Reference docs follow a specific mixture of manually created and auto-generated page content.

A page may look something like this:

---
template: api-doc.html

constructors:
  - name: 'Constructor'
    description: 'Creates a new instance of this class.'

methods:
  - name: 'getString'
    description: 'Gets a String.'
    type:
      name: String
      type: object
---

# <api__class></api__class> Constructor

An example class to show how the page structure may look like.

custom HTML tags¶

There is a collection of custom HTML tags that are used to render specific text in certain styles.
Below is a list of all custom tags. Note that these tags only render on the actual site and not within the repository when viewing the source.

<api__class></api__class>:
<api__interface></api__interface>:
<api__enum></api__enum>:
<api__record></api__record>:
<api__abstract></api__abstract>:
<api__static></api__static>:
<api__final></api__final>:
<api__notnull></api__notnull>:
<api__nullable></api__nullable>:
<api__deprecated></api__deprecated>:

In addition are there two classes used within span tags to colour the text, to indicate their type:

<span class="api-type__object">Object</span>: Object
<span class="api-type__primitive">primitive</span>: primitive

Auto-generated content¶

A page template is used to auto-generate the page content based on available YAML frontmatter.
Depending on the frontmatter available will the template call a jinja2 Macro to generate a Summary and Detailed info on the page for the respective frontmatter data.

There are 5 frontmatter options, each following a specific structure:

Constructors
Nested Classes
Enum Constants
Methods
Inherits

Constructors¶

constructors:
  - name: '<string>'
    description: '<string>'
    parameters:
      - name: '<string>'
        description: '<string>'
        type: '<string>'
        attributes:
          - '<string>'
    deprecated: '<string>'
    throws:
      - name: '<string>'
        description: '<string>'
    seealso:
      - name: '<string>'
        link: '<string>'

Options:

name - The name to display for the Constructor summary and detail. This should include any parameters the Constructor has, but without any parameter name.
description - The description to display for the Constructor.
parameters - List of parameters to display.
- name - Name of the parameter to display.
- description - Description of the parameter.
- type - The type this parameter is.
- attributes - List of attributes (i.e. nullability) to display. The provided values will be turned into <api__{name}></api__{name}> tags that will be prependet to the parameter name.
deprecated - Adds a notice about the deprecation of this Constructor in the form of a deprecation label and a deprecated section with the provided <string> as explanation.
throws - List of possible throws to display.
- name - Name of the throw to display.
- description - Description of the throw.
seealso - List of "See also" text to display.
- name - Name of the See also link.
- link - Link (Relative, absolute or URL) to use for the See also text.

Nested Classes¶

classes:
  - name: '<string>'
    description: '<string>'
    type: '<string>'
    link: '<string>'

Options:

name - The name to display for the Nested Classes Summary.
description - The description of the nested class.
type - Modifier and type of the nested class.
link - Link to the nested class.

Enum Constants¶

enums:
  - name: '<string>'
    description: '<string>'
    type: '<string>'
    deprecated: '<string>'
    seealso:
      - name: '<string>'
        link: '<string>'

Options:

name - The name to display for the Enum summary and detail. This should include any parameters the Enum has, but without any parameter name.
description - The description to display for the Enum.
type - The return type to display. Will default to API Reference Docs Structure if not set.
deprecated - Adds a notice about the deprecation of this Enum in the form of a deprecation label and a deprecated section with the provided <string> as explanation.
seealso - List of "See also" text to display.
- name - Name of the See also link.
- link - Link (Relative, absolute or URL) to use for the See also text.

Methods¶

methods:
  - name: '<string>'
    description: '<string>'
    type:
      name: '<string>'
      type: '<string>'
      link: '<string>'
    attributes:
      - '<string>'
    parameters:
      - name: '<string>'
        description: '<string>'
        type: '<string>'
        attributes:
          - '<string>'
    returns: '<string>'
    deprecated: '<string>'
    throws:
      - name: '<string>'
        description: '<string>'
    seealos:
      - name: '<string>'
        link: '<string>'

Options:

name - The name to display for the Method summary and detail. This should include any parameters the Method has, but without any parameter name.
description - The description to display for the Method.
type - Options for object type to display.
- name - Displayed name of the object.
- type - Object type. Can be either object or primitive which would be used in a class name for styling.
- link - Link (Relative, absolute or URL) to use for the type name.
attributes - List of attributes (i.e. nullability) to display. The provided values will be turned into <api__{name}></api__{name}> tags that will be prependet to the name.
parameters - List of parameters to display.
- name - Name of the parameter to display.
- description - Description of the parameter.
- type - The type this parameter is.
- attributes - List of attributes (i.e. nullability) to display. The provided values will be turned into <api__{name}></api__{name}> tags that will be prependet to the parameter name.
returns - Possible return values.
deprecated - Adds a notice about the deprecation of this Method in the form of a deprecation label and a deprecated section with the provided <string> as explanation.
throws - List of possible throws to display.
- name - Name of the throw to display.
- description - Description of the throw.
seealso - List of "See also" text to display.
- name - Name of the See also link.
- link - Link (Relative, absolute or URL) to use for the See also text.

Inherits¶

inherits:
  '<string>':
    link: '<string>'
    methods:
      - '<string>'

Options:

inherits.<string> - Classpath used to display in the text Methods inherited from <string>
link - Link to use for the classpath text.
methods - List of strings to display. Each will be linked using {link}#{method}