nesC Source Documentation

Overview

The nesC compiler includes a facility for automatically generating documentation from nesC source code. The basic structure of the generated documentation is taken from the source code, with one HTML file produced from each nesC source file. Documentation is not produced for items in included C files, or header files.

Program authors can augment the automatically generated documentation by including specially formatted comments in their source code. The formatting of these comments is patterned after the javadoc documentation specification from SUN's Java language specification.

Documentation Comment Style

Documentation comments in nesC must begin with the characters /**. (Note the additional * character, beyond the requirement for a normal comment.) These special comments may be placed in the following locations:

At the beginning of a nesC source file.
Before command and event declarations in interfaces
Before command, event, or task definitions in component implementations
Before the declaration of component-global variables in component implementations
(hopefully soon) Before message struct declarations

Within these comments, the first full sentance (ie, everything before the first '.' character) is used as a short description of the item, in various summary lists. The full text (including the first sentance) is used for longer descriptions.

The documentation parser recognizes the following commands within documentation-style comments:

@param paramname text text text: Describes a parameter to a function
@return text text text: Describes the return value of a function
@author text text text: Lists an author of the file; multiple @author strings are allowed.
@modified text text text: Lists a modification.

Additionally, HTML tags can be embedded in documentation-style comments. This is useful for adding better formatting for things such as bulleted lists, etc.

Example

The following source snippet illustrates the use of documentation-style comments.


/**
 * One-line component description.
 *
 * More text goes here, to give more details to the description.
 *
 * @author Alice
 * @author Bob
 * @modified 3/3/2003 Added meaningful documentation.
 *
 **/
module Foo {
  provides {
    interface SomeInteface;
  }
  uses {
    interface OtherInterface;
  }
}
implementation {
  /**
   * A state variable.  Why not?
   **/
  bool state;

  /**
   * Do some stuff.  Doing some stuff is better than doing no stuff,
   * although not as good as doing all stuff.
   *
   * @param count The number of things to do.
   * @param size The size of each thing.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  command result_t SomeInterface.doStuff(int count, int size) {
    OtherInterface.reallyDoStuff(count,size);
    return SUCCESS;
  }


  /**
   * Handle the response event generated by the
   * OtherInterface.reallyDoStuff() call.  This event handler
   * currently does nothing.
   *
   * @return Always returns <code>SUCCESS</code>
   **/
  event result_t OtherInterface.stuffDone()
  {
    return SUCCESS;
  }
}

Generating documentation

Documentation generation is enabled by passing appropriate arguments to the nesdoc program. It has similar syntax to the ncc compiler. For descriptions of these arguments, please see the ncc man page. To generate documentation, passing the same arguments to nesdoc as one passes to ncc to compile generally works.

Installing Graphviz

Basic HTML documentation can be generated with no special installation. For nicer display of component graphs, however, we recommend that you install the graphviz package from AT&T.

Using graphviz requires that you have the freefont2 libraries installed. Although there are undoubtedly other ways to get things working, the following steps are known to work on both linux and cygwin:

Install freetype2, libjpeg, libpng, and libz. Links to these can be found on the graphviz web page.
Install the latest version of graphviz from www.graphviz.org. You will need at least version 1.8.8. We have verified that things work with both 1.8.8 and 1.8.9.