OMNeT++ provides a tool which can generate HTML documentation from NED files and message definitions. Like Javadoc and Doxygen, the NED documentation tool makes use of source code comments. The generated HTML documentation lists all modules, channels, messages, etc., and presents their details including description, gates, parameters, assignable submodule parameters, and syntax-highlighted source code. The documentation also includes clickable network diagrams (exported from the graphical editor) and usage diagrams as well as inheritance diagrams.
The documentation tool integrates with Doxygen, meaning that it can hyperlink simple modules and message classes to their C++ implementation classes in the Doxygen documentation. If the C++ documentation is generated with some Doxygen features turned on (such as inline-sources and referenced-by-relation, combined with extract-all, extract-private and extract-static), the result is an easily browsable and very informative presentation of the source code.
NED documentation generation is available as part of the OMNeT++ IDE.
Documentation is embedded in normal comments. All // comments
that are in the “right place” (from the documentation tool's
point of view) will be included in the generated documentation.
Example:
//
// An ad-hoc traffic generator to test the Ethernet models.
//
simple Gen
{
parameters:
string destAddress; // destination MAC address
int protocolId; // value for SSAP/DSAP in Ethernet frame
double waitMean @unit(s); // mean for exponential interarrival times
gates:
output out; // to Ethernet LLC
}
One can also place comments above parameters and gates, which is better suited for long explanations. Example:
//
// Deletes packets and optionally keeps statistics.
//
simple Sink
{
parameters:
// Turns statistics generation on/off. This is a very long
// comment because it has to be described what statistics
// are collected.
bool collectStatistics = default(true);
gates:
input in;
}
Lines that start with //# will not appear in the generated documentation. Such lines can be used to make “private” comments like FIXME or TODO, or to comment out unused code.
//
// An ad-hoc traffic generator to test the Ethernet models.
//# TODO above description needs to be refined
//
simple Gen
{
parameters:
string destAddress; // destination MAC address
int protocolId; // value for SSAP/DSAP in Ethernet frame
//# double burstiness; -- not yet supported
double waitMean @unit(s); // mean for exponential interarrival times
gates:
output out; // to Ethernet LLC
}
Comments should be written where the tool will find them. This is a) immediately above the documented item, or b) after the documented item, on the same line.
In the former case, make sure there is no blank line left between the comment and the documented item. Blank lines detach the comment from the documented item.
Example:
// This is wrong! Because of the blank line, this comment is not
// associated with the following simple module!
simple Gen
{
...
}
Do not try to comment groups of parameters together. The result will be awkward.
One can reference other NED and message types by name in comments. There are two styles in which references can be written: automatic linking and tilde linking. The same style must be following throughout the whole project, and the correct one must be selected in the documentation generator tool when it is run.
In the automatic linking style, words that match existing NED of message types are hyperlinked automatically. It is usually enough to write the simple name of the type (e.g. TCP), one does not need to spell out the fully qualified type (inet.transport.tcp.TCP), although that is also allowed.
Automatic hyperlinking is sometimes overly agressive. For example, when the words IP address appear in a comment and the project contains an IP module, it will create a hyperlink to the module, which is not desirable. One can prevent hyperlinking of a word by inserting a backslash in front it: \IP address. The backslash will not appear in the HTML output. The <nohtml> tag will also prevent hyperlinking words in the enclosed text: <nohtml>IP address</nohtml>. On the other hand, if a backslash needs to be printed immediately in front of a word (e.g. output “use \t to print a Tab”), use either two backslashes (use \\t...) or the <nohtml> tag (<nohtml>use \t...</nohtml>). Backslashes in other contexts (i.e. when not in front of a word) do not have a special meaning, and are preserved in the output.
The detailed rules:
In the tilde style, only words that are explicitly marked with a tilde are subject to hyperlinking: ~TCP, ~inet.transport.tcp.TCP.
To produce a literal tilde followed by an identifier in the output (for example, to output “the ~TCP() destructor”), the tilde character needs to be doubled: the ~~TCP() destructor.
The detailed rules:
When writing documentation comments longer than a few sentences, one often needs structuring and formatting facilities. NED provides paragraphs, bulleted and numbered lists, and basic formatting support. More sophisticated formatting can be achieved using HTML.
Paragraphs can be created by separating text by blanks lines. Lines beginning with “-” will be turned into bulleted lists, and lines beginning with “-#” into numbered lists. An example:
// // Ethernet MAC layer. MAC performs transmission and reception of frames. // // Processing of frames received from higher layers: // - sends out frame to the network // - no encapsulation of frames -- this is done by higher layers. // - can send PAUSE message if requested by higher layers (PAUSE protocol, // used in switches). PAUSE is not implemented yet. // // Supported frame types: // -# IEEE 802.3 // -# Ethernet-II //
The documentation tool understands the following tags and will render them accordingly: @author, @date, @todo, @bug, @see, @since, @warning, @version. Example usage:
// // @author Jack Foo // @date 2005-02-11 //
Common HTML tags are understood as formatting commands. The most useful tags are: <i>..</i> (italic), <b>..</b> (bold), <tt>..</tt> (typewriter font), <sub>..</sub> (subscript), <sup>..</sup> (superscript), <br> (line break), <h3> (heading), <pre>..</pre> (preformatted text) and <a href=..>..</a> (link), as well as a few other tags used for table creation (see below). For example, <i>Hello</i> will be rendered as “Hello” (using an italic font).
The complete list of HTML tags interpreted by the documentation tool are: <a>, <b>, <body>, <br>, <center>, <caption>, <code>, <dd>, <dfn>, <dl>, <dt>, <em>, <form>, <font>, <hr>, <h1>, <h2>, <h3>, <i>, <input>, <img>, <li>, <meta>, <multicol>, <ol>, <p>, <small>, <span>, <strong>, <sub>, <sup>, <table>, <td>, <th>, <tr>, <tt>, <kbd>, <ul>, <var>.
Any tags not in the above list will not be interpreted as formatting commands but will be printed verbatim -- for example, <what>bar</what> will be rendered literally as “<what>bar</what>” (unlike HTML where unknown tags are simply ignored, i.e. HTML would display “bar”).
With links to external pages or web sites, its useful to add the target="_blank" attribute to ensure pages come up in a new browser tab, and not in the current frame. Alternatively, one can use the target="_top" attribute which replaces all frames in the current browser.
Examples:
// // For more info on Ethernet and other LAN standards, see the // <a href="http://www.ieee802.org/" target="_blank">IEEE 802 // Committee's site</a>. //
One can also use the <a href=..> tag to create links within the page:
// // See the <a href="#resources">resources</a> in this page. // ... // <a name="resources"><b>Resources</b></a> // ... //
One can use the <pre>..</pre> HTML tag to insert source code examples into the documentation. Line breaks and indentation will be preserved, but HTML tags continue to be interpreted (they can be turned off with <nohtml>, see later).
Example:
// <pre>
// // my preferred way of indentation in C/C++ is this:
// <b>for</b> (<b>int</b> i = 0; i < 10; i++) {
// printf(<i>"%d\n"</i>, i);
// }
// </pre>
will be rendered as
// my preferred way of indentation in C/C++ is this:
for (int i = 0; i < 10; i++) {
printf("%d\n", i);
}
HTML is also the way to create tables. The example below
// // <table border="1"> // <tr> <th>#</th> <th>number</th> </tr> // <tr> <td>1</td> <td>one</td> </tr> // <tr> <td>2</td> <td>two</td> </tr> // <tr> <td>3</td> <td>three</td> </tr> // </table> //
will be rendered approximately as:
|
# | number |
| 1 | one |
| 2 | two |
| 3 | three |
In some cases, one needs to turn off interpreting HTML tags (<i>, <b>, etc.) as formatting, and rather include them as literal text in the generated documentation. This can be achieved by surrounding the text with the <nohtml>...</nohtml> tag. For example,
// Use the <nohtml><i></nohtml> tag (like <tt><nohtml><i>this</i></nohtml><tt>) // to write in <i>italic</i>.
will be rendered as “Use the <i> tag (like <i>this</i>) to write in italic.”
<nohtml>...</nohtml> will also prevent opp_neddoc from hyperlinking words that are accidentally the same as an existing module or message name. Prefixing the word with a backslash will achieve the same. That is, either of the following will do:
// In <nohtml>IP</nohtml> networks, routing is...
// In \IP networks, routing is...
Both will prevent hyperlinking the word IP in case there is an IP module in the project.
The title page is the one that appears in the main frame after opening the documentation in the browser. By default, it contains a boilerplate text with the title “OMNeT++ Model Documentation”. Model authors will probably want to customize that, and at least change the title be more specific.
A title page is defined with a @titlepage directive. It needs to appear in a file-level comment.
While one can place the title page definition into any NED or MSG file, it is probably a good idea to create a dedicated NED file for it. Lines up to the next @page line or the end of the comment (whichever comes first) are interpreted as part of the page.
The page should start with a title, as the documentation tool doesn't add one. Use the <h1>..</h1> HTML tag for that.
Example:
// // @titlepage // <h1>Ethernet Model Documentation</h1> // // This documents the Ethernet model created by David Wu and refined by Andras // Varga at CTIE, Monash University, Melbourne, Australia. //
One can add new pages to the documentation using the @page directive. @page may appear in any file-level comment, and has the following syntax:
// @page filename.html, Title of the Page
Choose a file name that doesn't collide with other files generated by the documentation tool. If the file name does not end in .html, it will be appended. The page title will appear at the top of the page as well as in the page index.
The lines after the @page line up to the next @page line or the end of the comment will be used as the page body. One does not need to add a title because the documentation tool automatically inserts the one specified in the @page directive.
Example:
// // @page structure.html, Directory Structure // // The model core model files and the examples have been placed // into different directories. The <tt>examples/</tt> directory... // // // @page examples.html, Examples // ... //
One can create links to the generated pages using standard HTML, using the <a href="...">...</a> tag. All HTML files are placed in a single directory, so one doesn't have to worry about directories.
Example:
// // @titlepage // ... // The structure of the model is described <a href="structure.html">here</a>. //
The @externalpage directive allows one to add externally created pages into the generated documentation. @externalpage may appear in a file-level comment, and has a similar syntax as @page:
// @externalpage filename.html, Title of the Page
The directive causes the page to appear in the page index. However, the documentation tool does not check if the page exists, and it is the user's responsibility to copy the file into the directory of the generated documentation.
External pages can be linked to from other pages using the <a href="...">...</a> tag.
The @include directive allows one to include the content of a file into a documentation comment. @include expects file name or path; if a relative path is given, it is interpreted as relative to the file that includes it.
The line of the @include directive will be replaced by the content of the file. The lines of the included file do not need to start with //, but otherwise they are processed in the same way as the NED comments. They can include other files, but circular includes are not allowed.
// ... // @include ../copyright.txt // ...