TWiki . Main . DocumentationStyle	TWiki webs: Main | TWiki | Test
	Main . { Main . { Home | Users | Changes | Index | Search | Go } }

• General
  • Documentation Classes
• Groups
• Files
• Pages
• Comment Style
• FieldContainer

General

The main philosophy behind our commenting is: comment as much as needed, but keep the headers clean. Furthermore the code documentation serves two purposes: as a documentation of the code itself on the per-method level and as a documentation of the concepts behind it. This latter part can also be extracted into a separate document, the Starter Guide.

The Starter Guide uses the Doxygen \page feature to define its contents. All Related Pages will be extracted from the documentation and put together as the Starter Guide. To allow this the SG has priority, i.e. all information that should go into the SG has to be put on a \page. This page should be \ref ed from the class and function documentation when it is necessary.

Documentation Classes

There are different kinds of users of a system like OpenSG.

The first are the real users. They just want to use the system as it is. They need to know how to create and manipulate objects and what kinds of objects there are.

The second are the extenders. They are somewhat advanced users, who need to add structures to the system. Given the structure of OpenSG, that entails a number of things which normal users don't care about.

The last are the developers. These are people who really want to understand how things work internally, because they want to extend them or fix real bugs. They need to know about internal classes and how the different parts of the system interact on a very low level.

The level of detail given in a developer documentation can confuse a standard user and doesn't help him solve his problems. Thus there are three different levels of documentation in OpenSG: user, extender and developer. These levels are built on each other, i.e. the extender docs contain all the user docs and the dev docs contain all the extender docs.

To exclude parts of the code from a certain documentation level there are some preprocessor symbols that are only set during documentation creation.

OSG_DO_DOC and DOXYGEN_SHOULD_SKIP_THIS are just set for documentation and can be used with #ifndef to remove parts from the documentation. OSG_DOC_LEVEL is set to 1, 2 or 3, for user, extender and developer documentation. Alternatively there are the OSG_DOC_EXT and OSG_DOC_DEV defines for specific levels.

The primary use of these values is to exclude some classes from being added to the code.

#if !defined(OSG_DO_DOC) || defined(OSG_DOC_DEV)

class reallyInternalClass
{};

#endif            // exclude from doc

If not the whole class, but only some parts of the documentation text should be only for specific groupd, the ext/endext and dev/enddev commands can be used.

/*! This class does bla. \ext To extend it you need foo. \endext \dev Internally it uses bar and baz. \enddev 
*/

Groups

Doxygen features a hierarchical group concept (known as Modules in the HTML documentation) to organize classes/elements that are not necessarily derived from each other. These groups also allow overcoming problems in terms of documenting template constructs, which don't fit well with the standard documentation model.

The directory structure forms the main backbone of the groups, but it is advisable to add new groups to structure the contents of the libraries/directories.

To prevent namespace aliasing problems the names of the Groups should be roughly based on the directory name, with a prepended Grp. Lower-level groups should be roughly based on the directory name, with a prepended Grp.

/*! \defgroup GrpBaseBaseVolume
    \ingroup GrpBaseBase
...

Files

The documentation for groups and related pages (i.e. the Starter Guide) should be in separate files to prevent blowing up the source files with documentation to get around having to decide where to put the documentation for parts that affect multiple classes.

These files have the extension .dox and should have a capitalized name, e.g. Material.dox. They are not collected automatically, they have to manually be inserted into the DOC_PAGES variable in the Doc/Makefile. The order of the pages in that variable also defines the order that the pages will have in the Starter Guide.

Pages

Related pages keep all the documentation that should appear in the Starter Guide. Pages are named starting with Page, followed by the library name and a name that describes the contents of the page, e.g PageSystemMaterial. Note that page names have to be unique, as every page is turned into a separate file by doxygen. The same naming convention applies to sections, subsections etc.

Per default every page is a chapter in the Doxygen LaTeX? documentation. This either turns into very few, very large pages, which are hard to read and modify, or into a large of number of small chapters in the Starter Guide. Both of which are not desirable.

Thus per default the pages in the OpenSG documenation are just turned into sections. To create a new chapter you need to add \latexonly Starter:NewChapter \endlatexonly in the page's comment, preferredly right at the top.

Comment Style

Doxygen is used for documentation generation, and the QT comment style (/*!) is used, because it allows separating the brief from the full comment.

Classes

Only the brief comment should be in the header, the full comment should be in the source. Every class should have a brief comment, as they are useful to jump to the documentation from the top of the page, and they are shown on the Compound List.

Classes should be added to their respective group(s). Groups are an important aid for useful structuring, use them and add new ones when it makes sense.

Parts

The public, protected and private parts should be marked with a line like this:

   /*==========================  PUBLIC  =================================*/

In general comments like this can be used to differentiate different parts, e.g. forwards from the main class or classes from each other.

Methods

Method shouldn't be documented in the header, good method and parameter names should speak for themselves. Instead use doxygen \name to group them.

Example:

    /*---------------------------------------------------------------------*/
    /*! \name                   Destructors                            */
    /*! \{                                                             */

    virtual ~BoxVolume(void); 

    /*! \}                                                              */

You can give a detailed documentation in the .cpp file. Note that this is not necessary for derived methods whose behaviour differs from the base classes' method, as Doxygen's "Reimplemented from" link is a very quick way to get to the documentation. Documentation should be in base classes.

Code

The ordering in the .cpp files should be:

• includes
• group definition(s) if needed
• full class documentation
• static variables
• methods in the same order as in the header

Comment every method/function to explain what it does and what's special about it. But only if it's not obvious from the name! Adding a comment like the following is not necessary:

/*! get foo value */
int getFoo(void);

Don't use the \brief comments, though. This keeps the member list at the top of the page short and concise. Just use free text for documentation, forget the structured comments like \param, they just make the documentation longer and only very rarely add important information. If there are things to know about specific parameters, especially legal and iilegal value ranges and

Do use \warning to talk about unintuitive side-effects or constraints of a method.

FieldContainer

FieldContainer are the central data storage units in OpenSG. One feature of FieldContainers is that they're split into an automatically generated Base and the real class. As the base class keeps the real data the documentation for the classes functions should be in the base class to keep the relaton to the data. To do this and not lose the documentation when interfaces change it will have to be put in the .fcd file. The derived class should reference the base class first thing in the documentation to lead the users to the right spot.

For some FCs it will make sense to put the actual description in the starter guide. For these it's ok to put a direct link to the starter guide into the class docs.

-- DirkReiners - 23 Oct 2002