Apidoc File Tutorial

The systems and their APIs are described by apidoc files; either written in XML or a markdown based format. The schema document describes the full details of the XML format. The apidoc.md document described the details of the markdown format.

An apidoc file might describe multiple systems. In general it is a good idea to put the description of each top level system and its subsystems in separate file and use the top level refname as filename. In the examples below we would name the XML file foo.xml and the markdown file foo.md.

This is an example of an XML apidoc file:

<apidoc>
  <system refname="foo">
    <abstract>nothing says foo like we do</abstract>
    <description>
      to foo or not to foo that's a question
      yadayada,...
    </description>
  </system>
</apidoc>

This simply describes that there exists a system called foo and then provide the short and long descriptions of what the purpose of this system is.

The markdown version of the same information is:

# foo -- nothing says foo like we do

to foo or not to foo that's a question
yadayada,...

In general the markdown syntax is much easier to use if you maintain these files by hand; while the XML format might be more appropriate for automatically generated apidoc files. Internally in apidoc the markdown files are converted to the XML format before they are processed further.

Refnames

foo
foo.bar
foo.bar/f1
foo.bar/f2.ext

How to describe systems with APIs

<apidoc>
  <system refname="foo">
    <abstract>nothing says foo like we do</abstract>
    <description>
      to foo or not to foo that's a question
      yadayada,...
    </description>
    <api refname="f1">
      <abstract>perform the f1 transformation on stuff</abstract>
      <description>
        explain the details of what the f1 function does
        yadayada,...
      </description>
    </api>
  </system>
</apidoc>

# foo -- nothing says foo like we do

to foo or not to foo that's a question
yadayada,...

## f1 -- perform the f1 transformation on stuff

explain the details of what the f1 function does
yadayada,...

How to describe client systems

<apidoc>
  <system refname="foo">
    <abstract>nothing says foo like we do</abstract>
    <uses ref="bar"/>
    <uses ref="sebra.ldap/frost">authentication</uses>
    <description>
      to foo or not to foo that's a question
      yadayada,...
    </description>
  </system>
</apidoc>

For the markdown version we simply inline the <uses> elements before the description.

# foo -- nothing says foo like we do

<uses ref="bar"/>
<uses ref="sebra.ldap/frost">authentication</uses>

to foo or not to foo that's a question
yadayada,...

System classes

<apidoc>
  <system refname="foo">
    <abstract>nothing says foo like we do</abstract>
    <class name="website"/>
    <description>
      to foo or not to foo that's a question
      yadayada,...
    </description>
  </system>
</apidoc>

For the markdown version we simply inline the <class> element before the description.

# foo -- nothing says foo like we do

<class name="website"/>

to foo or not to foo that's a question
yadayada,...