Documentation

When you put a tool plugin or an app on sale, it is important to provide documentation for it. Sometimes, it may be enough to write a good description in the store when submitting a component, but comprehensive documentation makes it easier to start using your component and thus improves your sales.

All formal and informal documentation should be placed under a directory called doc at the root of your component’s installation directory. Documentation files are written in Markdown and saved using UTF-8 encoding. Formal documentation is used by the VisionAppster Store to automatically generate documentation for your tools and public APIs.

Documenting tool plugins

Formal documentation of tools goes under doc/tool in a .vapkg file. The names of files in that directory must match tool names. For example, if your component provides a tool called CountPeople, the name of the corresponding documentation file should be CountPeople.md. The contents of the directory out of which you build a .vapkg could be like this:

component.json
linux-x86_64/peoplecounter.toolplugin
linux-arm_32/peoplecounter.toolplugin
linux-arm_64/peoplecounter.toolplugin
windows-x86_64/peoplecounter.toolplugin
doc/tool/CountPeople.md

Use the following template for tool documentation:

Name of tool
============

Really short description of a tool, preferably one line.

A more comprehensive explanation of the purpose and functionality.
This may span multiple paragraphs.

This file should be readable as such. Line length should not exceed 70
characters.

Markdown tables are supported:

| Row   | Value   |
|:-----:|:-------:|
| Row 1 | Value 1 |
| Row 2 | Value 2 |

~~~{.py}
# Use a style class (.py) to specify language in code blocks.
def func():
    pass
~~~

Inputs
------

General description of inputs, if needed.

@param[in] inputParameterName Description. This may span multiple
    lines until the next empty line. Note that the @param syntax is
    our custom extension to markdown that lets us to generate
    context-sensitive inline documentation for the Builder.

    If there are at least four spaces at the beginning of a line, the
whole paragraph until the next empty line belongs to the same
parameter description.

@param[in] anotherParameter And its description.

This paragraph starts at column 1 and does not belong to the parameter
description any more. It may provide additional information related to
input arguments.

Outputs
-------

@param[out] outputParameterName Description. Similar stuff here.

Documenting public APIs

If your component contains an app with a public API, its documentation should be placed under doc/api. This time, the names of documentation files must match the names of API functions. For example, if your app provides a function called countPeople, its documentation goes to doc/api/countPeople.md.

The format of API function documentation is the same as that of tools:

Name of API function
====================

Description.

Inputs
------

@param[in] inputParameterName Description.

@param[in] anotherParameter Description.

Outputs
-------

@param[out] outputParameterName Description.