The XML Documentation of a Module

In this tutorial we show how to write the XML documentation of an iCub module.

Introduction

The convenience of providing the documentation of an iCub module in the XML format is twofold: (1) it standardizes the way we declare relevant information for the module (arguments, dependencies ...) and serves thus to automatically generate the Doxygen documentation; (2) the XML file accompanying the module is indeed the description file itself used by the yarpmanager.

Heading

The XML file should start with the following lines that contain the instructions on how to produce the Doxygen documentation from the XML itself:

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="yarpmanifest.xsl"?>

The description is all contained within the module section:

<module>
...
</module>

General Information on the Module

A bunch of dedicated key account for describing general information on the module as in the following:

<!-- <name> should match the executable file's name -->
<name>rpcIdl</name>
 
<!-- <doxygen-group> accounts for the "@ingroup" Doxygen key,
to declare <name> as a Doxygen tag belonging to the specified group -->
<doxygen-group>icub-module</doxygen-group>
 
<description>Example to show idl usage.</description>
 
<copypolicy>Released under the terms of the GNU GPL v2.0</copypolicy>
 
<version>1.0</version>
 
<description-long>
    Implements a trivial server that provides access to an integer.
    You can use html, for example to add a link to <a href="http://www.yarp.it"> the yarp page</a> and Doxygen tags.
 
    @subsection sec-intro Introduction
    This is the introduction. 123
 
    @subsection sec-details More stuff
    This is a detailed description, etc.
</description-long>
 
<!-- <authors> can have multiple <author> tags. -->
<authors>
    <author email="lorenzo.natale@iit.it"> Lorenzo Natale</author>
</authors>

Arguments

Here comes the arguments section that lists down all the command-line parameters of the module:

<!-- <arguments> can have multiple <param> tags -->
<arguments>
    <param default = "rpcIdl" desc="name of the module"> name </param>
    <param default = ""       desc="configuration file name"> from </param>
    <param default = ""       desc="select the current context"> context </param>
</arguments>

Data

The data section contains information on the input and output ports of the module:

<!-- <data> can have multiple <input> or <output> tags. -->
<data>
    <!-- input data if available-->
    <input>
        <!-- <type> refers to nominal type of data (e.g. ImageFrame, String). -->
        <type>Image</type>
 
        <!-- input port which receive images. -->
        <port carrier="tcp">/rpcIdl/img:i</port>
 
        <!-- required input means the execution of module depends on
        this input data. Notice that not all the input are required
        for a module to perform its task (e.g. control input, status
        request input). -->
        <required>no</required>
 
        <!-- priority forces the execution of module to be delayed
        until the required data becomes available on the port -->
        <priority>no</priority>
        <description>Feed images to rpcIdl using this port.</description>
    </input>
 
    <output type="service">
        <type>Image</type>
        <port carrier="udp">/rpcIdl/img:o</port>
        <description>Output image.</description>
    </output>
 
    <output>
        <type>yarp::os::Bottle</type>
        <port carrier="udp">/rpcIdl/target:o</port>
        <description>
            Outputs the x-y location of whatever is the output of the module:
            - int i value of y
            - int j value of x
        </description>
    </output>
</data>

Services

The services section describes the Thrift services exposed by the module according to the Interface Description Language rules contained in the rpcIdl.thrift file:

<services>
    <server>
        <type>IRpcServer</type>
        <idl>IRpcServer.thrift</idl>
        <port>/rpcIdl/server</port>
        <description>Command port</description>
    </server>
 
    <client>
        <type>IRpcServer</type>
        <idl>IRpcServer.thrift</idl>
        <port>/rpcIdl/client</port>
        <description>Control remote object</description>
    </client>
</services>

Dependencies

In the final sections dependencies and development we find further lists containing useful information to run the module.

<!-- physical and logical resource dependencies can be introduced in this
     section. Dependencies must follow resource conceptional models. Currently
     available resource models are 'memory', 'processor', 'storage', 'network',
     'yarp_port', 'platform' and 'gpu'. All resource dependencies should be introduced
     inside <computer></computer> tags. While resources described inside <computer>
     tags represent conjunctional dependency, resources from different <computer>
     tags can be seen as disjunctions. Meaning that If a module depend on either
     resource R1 or R2 they can be introduced inside two different <computer> tags.
     Resource dependencies should be introduced if they are really required. For
     example, if module's performance drops significantly in case of memory swapping,
     a memory resource dependency can be introduced with the required memory space. -->
<dependencies>
    <computer>
    </computer>
</dependencies>
 
<!-- specific libraries or header files which are used for development -->
<development>
    <header></header>
    <library></library>
</development>

Conclusion

Concluding, once processed the final Doxygen documentation will look like as in rpcIdl.

To install the description file in the location where all the xml are supposed to be just rely on the following cmake directive:

yarp_install(FILES rpcIdl.thrift DESTINATION ${ICUB_MODULES_INSTALL_DIR})