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.
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.