Documentation Guidelines

Documentation Guidelines

General

This page gives a brief introduction for Doxygen and Neddoc. We will focus on issues that are important for the documentation of the framework. For a full documentation of Doxygen please refer to doxygen manual. For more information on the Neddoc tool read chapter 11 of the OMNeT++ manual v3.0 or higher.

Documenting the c++ code using doxygen

Doxygen can analyze the structure of a C++ project and extract all comments in the source code and create an API reference manual. All comments that should be included in the manual have to have one of the following syntaxes:

/**
*
*/

///
///
///

The intermediate * is optional. All comments have to be in front of the object you want to document.

If you want to place the comment after the object you have to use the following syntax:

int id;  /**< host id */

For me the easiest way to learn things is to see examples, so here are is an example how to document a simple module.

/**
 * @brief general class for the network layer
 * 
 * This is the generic class for all network layer modules. If you
 * want to implement your own network layer you have to subclass your
 * module from this class.
 *
 * @param pmyhost pointer to parentmodule
 * @see BlackboardAccess
 *
 * @ingroup netwLayer
 * @author Daniel Willkomm
 **/
class NetwLayer : public BlackboardAccess
{
 protected:
  /** @brief gate ids*/
  /*@{*/
  int uppergateIn;
  int uppergateOut;
  int lowergateIn;
  int lowergateOut;
  /*@}*/

  /** @brief Total number of hosts in the network */
  int numHosts;
  ...

 public:
  Module_Class_Members( BasicNetwLayer , BlackboardAccess, 0 );

  /** @brief Initialization of the module and some variables*/
  virtual void initialize();

  /** @brief Called every time a message arrives*/
  void handleMessage(cMessage*);
  ...

All simple modules are documented in their corresponding .h and .cc file. The first thing is a brief and a detailed description of the module. The @param and @see tags can be used to list important parameters in the description and to offer the reader links with more information on the module (e.g. a link to the parent module).

Every class has to have the @author tag set. Additionally you should set the @ingroup tag so every class is at least member of one group. The different groups are explained on the Module Groups page.

Additionally important parameters and methods should be documented as well. The header file contains only the brief description for methods. The detailed description should be in the .cc files immediately above the method. A method should have a @author tag if the author of that method is different from the author of the module.

Important doxygen commands overview

@brief -- add a brief description
@param <name> -- specify a parameter in a detailed description
@return -- specify a functions return value in the detailed description
@author -- specify an author
@see or @sa <name> -- create a reference link
@ingroup <name> -- add a class to a group
@page <name> <title> -- create a c++ independent documentation
@ref <name> -- create a reference
@bug -- specify a bug
@todo -- specify a task for the todo list

Documenting the .ned and .msg files using opp_neddoc

As doxygen is not able to extract comments from .ned and .msg files OMNeT++ offers a tool called opp_neddoc that creates a documentation for OMNeT++ modules and messages. All comments you want to go into the documentation have to be marked with the following comment signs:

// 
// 
//

Here is an example of a properly documented .ned file:

// The nic (network interface card) is a compound module that contains the 
// MAC and PHY of a host within the Mobility Framework
//
// The BasicNic is the most simple nic you can create for the MF
//
// IMPORTANT:<br> In order to work with the ChannelControl module the snrEval
// module has to be called "snrEval" in the ned file.
//
// @sa BasicMacLayer, BasicDecider, BasicSnrEval
//
// @author Daniel Willkomm
module BasicNic 
    gates: 
        in: uppergateIn; // to upper layers
        out: uppergateOut; // from upper layers
    submodules: 
        mac: BasicMacLayer; 
        decider: BasicDecider; 
        snrEval: BasicSnrEval; 
    connections: 
        decider.uppergateOut --> mac.lowergateIn display "m=m,50,50,75,0"; 
        snrEval.uppergateIn <-- mac.lowergateOut display "m=m,25,0,25,0"; 
        snrEval.uppergateOut --> decider.lowergateIn display "m=m,73,0,50,50"; 
        mac.uppergateOut --> uppergateOut; 
        mac.uppergateIn <-- uppergateIn; 
endmodule

It is very important that the documentaton that belongs to the compound module defined in the .ned file is written directely above the module definition without any blank line!! If paramaters are to be documented, the comments can be written directly after the parameter definition into the same line. Alternatively the comment can also be written in an extra line above the parameter.

It makes sense to document the simple modules with the same comments as the corresponding class in the .h file. This way it is possible to find out about the general functionality of a module in the neddoc documentation and if further information about the implementation is needed one can read the corresponding documentation in the API Referance created by doxygen.

.msg files are documented the same way as the .ned files Here is an example for general documentation text for a message as well as for documenting the 'fields' of a message (parameters):

// A basic MAC (Media Access Control) packet format definition
// 
// subclass if you want to create your own MAC layer message class
//
// The basic MAC message only provides source and destination address
// and and the channel it should be send on
//
// @author Daniel Willkomm
message MacPkt{
    fields:
  int destAddr=-1; // destination mac address
  int srcAddr=-1; // source mac address
  int channelId=1; // channel to send / receive on
}