Apidoc Markdown Syntax
The apidoc files are XML files that describe a set of systems and the APIs they expose. Since authoring XML files by hand is a bit annoying while typing markdown is a joy the apidoc system provice a way to generate the apidoc files from markdown source.
The rules are simple. Just write regular markdown, but use lines prefixed with '#' or '##' to introduce sections describing systems or apis. The other syntactic forms for setting up h1 and h2 headers will not be recognized so don't use them. Don't suffix these lines with '#' or '##' either.
Lines on the form:
# <refname> -- <abstract>
introduce a new system. The refname can optionally be suffixed with a number enclosed in brackets to encode the configDB identifier of the given system (for example "sebra.elkat[16]").
One or more uses and class elements can be embedded directly before any description text for the system. To be recognized as such the start tag must start at the beginning of the line.
Lines on the form:
## <refname> -- <abstract>
introduce a new api within the preceeding system. Any text that follows the system or api introduction headers becomes the description.
A synopsis section can be embedded for an API by inlining a literal XML section for
it. The start and ending <synopsis> tag must be at the beginning of the line
to be recognized. For example we might specify the foo api within the grok system like this:
# grok -- grok this
Describe general what the grok system is about. Yadayada,...
## foo -- do the foo thing fast and correctly
<synopsis>
<httpservice action="http://.../foo">
...
</httpservice>
</synopsis>
Describe what the foo service actually does. Yadayada,...
### Examples
Describe examples showing the `foo` service in action. Yadayada,...