Creating Documentation¶

ns-3 supplies two kinds of documentation: expository “user-guide”-style chapters, and source code API documentation.

The “user-guide” chapters are written by hand in reStructuredText format (.rst), which is processed by the Python documentation system Sphinx to generate web pages and pdf files. The API documentation is generated from the source code itself, using Doxygen, to generate cross-linked web pages. Both of these are important: the Sphinx chapters explain the why and overview of using a model; the API documentation explains the how details.

This chapter gives a quick overview of these tools, emphasizing preferred usage and customizations for ns-3.

To build all the standard documentation:

$ ./waf docs

For more specialized options, read on.

Documenting with Sphinx¶

We use Sphinx to generate expository chapters describing the design and usage of each module. Right now you are reading the Documentation Chapter. The Show Source link in the sidebar will show you the reStructuredText source for this chapter.

Adding New Chapters¶

Adding a new chapter takes three steps (described in more detail below):

Choose Where? the documentation file(s) will live.
Link from an existing page to the new documentation.
Add the new file to the Makefile.

Where?¶

Documentation for a specific module, foo, should normally go in src/foo/doc/. For example src/foo/doc/foo.rst would be the top-level document for the module. The src/create-module.py script will create this file for you.

Some models require several .rst files, and figures; these should all go in the src/foo/doc/ directory. The docs are actually build by a Sphinx Makefile. For especially involved documentation, it may be helpful to have a local Makefile in the src/foo/doc/ directory to simplify building the documentation for this module (Antenna is an example). Setting this up is not particularly hard, but is beyond the scope of this chapter.

In some cases, documentation spans multiple models; the Network chapter is an example. In these cases adding the .rst files directly to doc/models/source/ might be appropriate.

Link¶

Sphinx has to know where your new chapter should appear. In most cases, a new model chapter should appear the in Models book. To add your chapter there, edit doc/models/source/index.rst

.. toctree::
   :maxdepth: 1

  organization
  animation
  antenna
  aodv
  applications
  ...

Add the name of your document (without the .rst extension) to this list. Please keep the Model chapters in alphabetical order, to ease visual scanning for specific chapters.

Makefile¶

You also have to add your document to the appropriate Makefile, so make knows to check it for updates. The Models book Makefile is doc/models/Makefile, the Manual book Makefile is doc/manual/Makefile.

# list all model library .rst files that need to be copied to $SOURCETEMP
SOURCES = \
        source/conf.py \
        source/_static \
        source/index.rst \
        source/replace.txt \
        source/organization.rst \
        ...
        $(SRC)/antenna/doc/source/antenna.rst \
        ...

You add your .rst files to the SOURCES variable. To add figures, read the comments in the Makefile to see which variable should contain your image files. Again, please keep these in alphabetical order.

Building Sphinx Docs¶

Building the Sphinx documentation is pretty simple. To build all the Sphinx documentation:

$ ./waf sphinx

To build just the Models documentation:

$ make -C doc/models

To see the generated documentation point your browser at doc/models/build/html.

As you can see, Sphinx uses Make to guide the process. The default target builds all enabled output forms, which in ns-3 are the multi-page html, single-page singlehtml, and pdf (latex). To build just the multi-page html, you add the html target:

$ make -C doc/models html

This can be helpful to reduce the build time (and the size of the build chatter) as you are writing your chapter.

Before committing your documentation to the repo, please check that it builds without errors or warnings. The build process generates lots of output (mostly normal chatter from LaTeX), which can make it difficult to see if there are any Sphinx warnings or errors. To find important warnings and errors build just the html version, then search the build log for warning or error.

ns-3 Specifics¶

The Sphinx documentation and tutorial are pretty good. We won’t duplicate the basics here, instead focusing on preferred usage for ns-3.

Start documents with these two lines:
```
.. include:: replace.txt
.. highlight:: cpp
```
The first line enables some simple replacements. For example, typing |ns3| renders as ns-3. The second sets the default source code highlighting language explicitly for the file, since the parser guess isn’t always accurate. (It’s also possible to set the language explicitly for a single code block, see below.)

Sections:

Sphinx is pretty liberal about marking section headings. By convention, we prefer this hierarchy:

.. heading hierarchy:
   ------------- Chapter
   ************* Section (#.#)
   ============= Subsection (#.#.#)
   ############# Sub-subsection

Syntax Highlighting:

To use the default syntax highlighter, simply start a sourcecode block:
Sphinx Source

Rendered Output
The ``Frobnitz`` is accessed by:: Foo::Frobnitz frob; frob.Set (...);
The Frobnitz is accessed by:

Foo::Frobnitz frob; frob.Set (...);
To use a specific syntax highlighter, for example, bash shell commands:
Sphinx Source

Rendered Output
.. sourcecode:: bash $ ls
$ ls
Shorthand Notations:

These shorthands are defined:
Sphinx Source

Rendered Output
|ns3|
ns-3
|ns2|
ns-2
|check|
$\checkmark$
:rfc:`6282`
RFC 6282

Documenting with Doxygen¶

We use Doxygen to generate browsable API documentation. Doxygen provides a number of useful features:

Summary table of all class members.

Graphs of inheritance and collaboration for all classes.

Links to the source code imlementing each function.

Links to every place a member is used.

Links to every object used in implementing a function.

Grouping of related classes, such as all the classes related to a specific protocol.

In addition, we use the TypeId system to add to the documentation for every class

The Config paths by which such objects can be reached.

Documentation for any Attributes, including Attributes defined in parent classes.

Documentation for any Trace sources defined by the class.

Doxygen operates by scaning the source code, looking for specially marked comments. It also creates a cross reference, indicating where each file, class, method, and variable is used.

Preferred Style¶

The preferred style for Doxygen comments is the JavaDoc style:

/**
 *  Brief description of this class or method.
 *  Adjacent lines become a single paragraph.
 *
 *  Longer description, with lots of details.
 *
 *  Blank lines separate paragraphs.
 *
 *  Explain what the class or method does, using what algorithm.
 *  Explain the units of arguments and return values.
 *
 *  \note Note any limitations or gotchas.
 *
 *  (For functions with arguments or return valued:)
 *  \param foo Brief noun phrase describing this argument.
 *  \param bar Note Sentence case, and terminating period.
 *  \return Brief noun phrase describing the value.
 *
 *  \internal
 *
 *  You can also discuss internal implementation details.
 *  Understanding this material shouldn't be necessary to using
 *  the class or method.
 */
 class Example

In this style the Doxygen comment block begins with two `*’ characters: /**, and precedes the item being documented.

For items needing only a brief description, either of these short forms is appropriate:

/** Destructor implementation. */
void DoDispose ();

int m_count;  //!< Count of ...

Note the special form of the end of line comment, //!<, indicating that it refers to the preceding item.

Some items to note:

Use sentence case, including the initial capital.

Use punctuation, especially `.’s at the end of sentences or phrases.

The \brief tag is not needed; the first sentence will be used as the brief description.

Every class, method, typedef, member variable, function argument and return value should be documented in all source code files which form the formal API and implementation for ns-3, such as src/<module>/model/*, src/<module>/helper/* and src/<module>/utils/*. Documentation for items in src/<module>/test/* and src/<module>/examples/* is preferred, but not required.

Useful Features¶

Inherited members will automatically inherit docs from the parent, (but can be replaced by local documentation).
1. Document the base class.
2. In the sub class mark inherited functions with an ordinary comment:
```
// Inherited methods
virtual void FooBar (void);
virtual int BarFoo (double baz);
```
  Note that the signatures have to match exactly, so include the formal argument (void)
  
  This doesn’t work for static functions; see GetTypeId, below, for an example.

Building Doxygen Docs¶

Building the Doxygen documentation is pretty simple:

$ ./waf doxygen

This builds using the default configuration, which generates documentation sections for all items, even if they do not have explicit comment documentation blocks. This has the effect of suppressing warnings for undocumented items, but makes sure everything appears in the generated output.

When writing documentation, it’s often more useful to see which items are generating warnings, typically about missing documentation. To see the full warnings list, use the doc/doxygen.warnings.report.sh script:

$ doc/doxygen.warnings.report.sh
Waf: Entering directory `build'
...
Waf: Leaving directory `build'
'build' finished successfully (3m24.094s)

Rebuilding doxygen docs with full errors...Done.


Report of Doxygen warnings
----------------------------------------

(All counts are lower bounds.)

Warnings by module/directory:

Count Directory
----- ----------------------------------
3844 src/lte/model
1718 src/wimax/model
1423 src/core/model
....
 138 additional undocumented parameters.
----------------------------------------
 15765 total warnings
   126 directories with warnings


Warnings by file (alphabetical)

Count File
----- ----------------------------------
  17 doc/introspected-doxygen.h
  15 examples/routing/manet-routing-compare.cc
  26 examples/stats/wifi-example-apps.h
....
----------------------------------------
   967 files with warnings


Warnings by file (numerical)

Count File
----- ----------------------------------
 374 src/lte/model/lte-asn1-header.h
 280 src/lte/model/lte-rrc-sap.h
 262 src/lte/model/lte-rrc-header.h
....
----------------------------------------
   967 files with warnings


Doxygen Warnings Summary
----------------------------------------
   126 directories
   967 files
 15765 warnings

The script modifies the configuration to show all warnings, and to shorten the run time. As you can see, at this writing we have a lot of undocumented items. The report summarizes warnings by module src/*/*, and by file, in alphabetically and numerical order.

The script has a few options to pare things down and make this more manageable. For help, use the -h option. Having run it once to do the Doxygen build and generate the full warnings log, you can reprocess the log file with various “filters,” without having to do the full Doxygen build by, again using the -s option. You can exclude warnings from */examples/* files (-e option), and/or */test/* files (-t).

Perhaps the most useful option when writing documentation comments is -m <module>, which will limit the report to just files matching src/<module>/*, and follow the report with the actual warning lines. Combine with -et and you can focus on the warnings that are most urgent in a single module:

$ doc/doxygen.warnings.report.sh -m mesh/helper
...
Doxygen Warnings Summary
----------------------------------------
  1 directories
  3 files
149 warnings


Filtered Warnings
========================================
src/mesh/helper/dot11s/dot11s-installer.h:72: warning: Member m_root (variable) of class ns3::Dot11sStack is not documented.
src/mesh/helper/dot11s/dot11s-installer.h:35: warning: return type of member ns3::Dot11sStack::GetTypeId is not documented
src/mesh/helper/dot11s/dot11s-installer.h:56: warning: return type of member ns3::Dot11sStack::InstallStack is not documented
src/mesh/helper/flame/flame-installer.h:40: warning: Member GetTypeId() (function) of class ns3::FlameStack is not documented.
src/mesh/helper/flame/flame-installer.h:60: warning: return type of member ns3::FlameStack::InstallStack is not documented
src/mesh/helper/mesh-helper.h:213: warning: Member m_nInterfaces (variable) of class ns3::MeshHelper is not documented.
src/mesh/helper/mesh-helper.h:214: warning: Member m_spreadChannelPolicy (variable) of class ns3::MeshHelper is not documented.
src/mesh/helper/mesh-helper.h:215: warning: Member m_stack (variable) of class ns3::MeshHelper is not documented.
src/mesh/helper/mesh-helper.h:216: warning: Member m_stackFactory (variable) of class ns3::MeshHelper is not documented.
src/mesh/helper/mesh-helper.h:209: warning: parameters of member ns3::MeshHelper::CreateInterface are not (all) documented
src/mesh/helper/mesh-helper.h:119: warning: parameters of member ns3::MeshHelper::SetStandard are not (all) documented

Now it’s just a matter of understanding the code, and writing some docs!

ns-3 Specifics¶

As for Sphinx, the Doxygen docs and reference are pretty good. We won’t duplicate the basics here, instead focusing on preferred usage for ns-3.

Use Doxygen Modules to group related items.

In the main header for a module, create a Doxgyen group:
```
/**
 *  \defgroup foo Foo protocol.
 */
```
Mark each associated class as belonging to the group:
```
/**
 *  \ingroup foo
 *
 *  Foo packet type.
*/
class Foo
```
Copy the Attribute help strings from the GetTypeId method to use as the brief descriptions of associated members.
\bugid{298} will create a link to bug 298 in our Bugzilla.
\pname{foo} in a description will format foo as a \param foo parameter, making it clear that you are referring to an actual argument.
\RFC{301} will create a link to RFC 301.
\internal should be used only to set off a discussion of implementation details, not to mark private functions (they are already marked, as private!)
Don’t create classes with trivial names, such as class A, even in test suites. These cause all instances of the class name literal `A’ to be rendered as links.

As noted above, static functions don’t inherit the documentation of the same functions in the parent class. ns-3 uses a few static functions ubiquitously; the suggested documentation block for these cases is:

Default constructor/destructor:

MyClass ();   //!< Default constructor
~MyClass ();  //!< Destructor

Dummy destructor and DoDispose:

/** Dummy destructor, see DoDispose. */
~MyClass ();

/** Destructor implementation */
virtual void DoDispose ();

GetTypeId:

/**
 *  Register this type.
 *  \return The object TypeId.
 */
static TypeId GetTypeId (void);

Creating Documentation¶

Documenting with Sphinx¶

Adding New Chapters¶

Where?¶

Link¶

Makefile¶

Building Sphinx Docs¶

ns-3 Specifics¶

Documenting with Doxygen¶

Preferred Style¶

Useful Features¶

Building Doxygen Docs¶

ns-3 Specifics¶

Table Of Contents

Previous topic

Next topic

This Page

Sphinx Source	Rendered Output
\|ns3\|	ns-3
\|ns2\|	ns-2
\|check\|	$\checkmark$
:rfc:`6282`	RFC 6282

Navigation

Creating Documentation¶

Documenting with Sphinx¶

Adding New Chapters¶

Where?¶

Link¶

Makefile¶

Building Sphinx Docs¶

ns-3 Specifics¶

Documenting with Doxygen¶

Preferred Style¶

Useful Features¶

Building Doxygen Docs¶

ns-3 Specifics¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation