Using Doxygen within SST

Introduction

Documentation of SST source code can be enhanced through the use of doxygen, which can create a user-friendly browseable reference, or nicely-formatted hardcopy output. For the latest SST Doxygen output online click here

Creating doxygen documentation

Documenting software using doxygen is straightforward. In a nutshell, normal source code comments can be supplemented with doxygen markup symbols, allowing doxygen to extract and format these comments and present them in a user-friendly document.

The best practical example can be seen in the SST file .../sst/core/component.h. Inspection of this source code header reveals a variety of useful doxygen documentation techniques that can be applied.

Various interesting bits of component.h will now be discussed.

Detailed Class Description

    24	namespace SST {
    25
    26	class LinkMap;
    27	class Module;
    28
    29	#define _COMP_DBG( fmt, args...) __DBG( DBG_COMP, Component, fmt, ## args )
    30
    31	/**
    32	 * Main component object for the simulation.
    33	 *  All models inherit from this.
    34	 */
    35	class Component {
    36	public:

A doxygen-style comment can be observed starting at line 31 and extending through line 34. It is unique in that the comment begins with “/**”.

Because it is located immediately prior to the class declaration on line 35 (with no intervening text), doxygen will consider this comment to contain the detailed description of the class. The text here will be placed in the Detailed Description area in the generated doxygen output. Be aware that only the first sentence of this comment text will be used when doxygen creates summary descriptions; the subsequent lines of comment text will also be used when doxygen creates detailed descriptions. Therefore, it is important that the first sentence of a detailed description contain a useful, concise summary.

NOTE: doxygen will always associate a doxygen-style comment with its nearest following item.

General Item Descriptions

    37	    /* Deprecated typedef */
    38	    typedef Params Params_t;
    39	
    40	    /** Constructor. Generally only called by the factory class. 
    41	        @param id Unique component ID
    42	    */
    43	    Component( ComponentId_t id );
    44	    virtual ~Component();
    45	
    46	    /** Returns unique component ID */
    47	    inline ComponentId_t getId() const { return id; }

A regular comment is seen at line 37. Because it does not begin with /**, doxygen will ignore this comment.

The Component class constructor method is described in a doxygen comment starting at line 40. Following the constructor comment is a brief description of the constructor’s argument “id” on line 41 using the @param command. Each argument of a method can be described in this manner. The form of this argument’s doxygen comment is

@param argument name argument description

Larger comments and cross references

   132	    /** Indicate permission for the simulation to end. This function is
   133	        the mirror of Component::registerExit(). It decrements the
   134	        global counter, which, upon reaching zero, indicates that the
   135	        simulation can terminate. @sa Component::registerExit() */
   136	    bool unregisterExit();
   137	
   138	    /** Register as a primary component, which allows the component to
   139	        specifiy when it is and is not OK to end simulation.  The
   140	        simulator will not end simulation natuarally (through use of
   141	        the Exit object) while any primary component has specified
   142	        primaryComponentDoNotEndSim().  However, it is still possible
   143	        for Actions other than Exit to end simulation.  Once all
   144	        primary components have specified
   145	        primaryComponentOKToEndSim(), the Exit object will trigger and
   146	        end simulation.
   147	
   148		This must be called during simulation wireup (i.e during the
   149		constructor for the component).  By default, the state of the
   150		primary component is set to OKToEndSim.
   151	
   152		If no component registers as a primary component, then the
   153		Exit object will not be used for that simulation and
   154		simulation termination must be accomplished through some other
   155		mechanism (e.g. --stopAt flag, or some other Action object).
   156	
   157	        @sa Component::primaryComponentDoNotEndSim()
   158	        @sa Component::primaryComponentOKToEndSim()
   159	    */
   160	    void registerAsPrimaryComponent();
   161	
   162	    /** Tells the simulation that it should not exit.  The component
   163		will remain in this state until a call to
   164		primaryComponentOKToEndSim().
   165	
   166	        @sa Component::registerAsPrimaryComponent()
   167	        @sa Component::primaryComponentOKToEndSim()
   168	    */

Doxygen also supports longer comments that provide additional detail into the operation and use of various items. As stated previously, the first sentence of detailed comments are used for summary descriptions, so it is important that the first sentence contain a concise, clear high-level characterization of the item being described.

At line 132, a long description of the unregisterExit() method begins. Line 133 contains an (inferred) reference to the Component::registerExit() method. These references are automatically created by doxygen if the item is visible to doxygen at documenation generation time. At line 135, an explicit reference to the Component::registerExit() method is made via the @sa (“see also”) command.

Additional doxygen formatting commands

There are a variety of formatting commands that doxygen recognizes that permit additional tailoring of the doxygen output. These can be useful in a variety of situations where the documentation can benefit from more fine-grained control of the content layout. These commands are documented here:

doxygen commands