Next: , Previous: Contributing documentation, Up: Contributing to Marsyas


1.2 Contributing source documentation

In your .h file, just after the namespace Marsyas \n { line, please include a short documentation snippet:

     namespace Marsyas
     {
     /**
         \ingroup Processing
         \brief Multiply input realvec with gain
     
     	Simple MarSystem example.  Just multiply the values of the input
     realvec with gain and put them in the output vector.  This object can be
     used as a prototype template for building more complicated MarSystems.
     
         Controls:
         - \b mrs_real/gain [w] : adjust the gain multiplier.
     */
     
     class Gain: public MarSystem
     {

Warning: the old convention included a \class Gain; this was a mistake in our understanding of Doxygen. Please do not include an explicit class name; just make sure that the doc snippet occurs above the class.

The [w] indicates that the control should be written and not (usefully) read. Valid options are [r], [w], and [rw].

The \ingroup GROUP will generally be Processing, Analysis, or Synthesis. For details about these categories, see MarSystem reference. For a complete list of all available groups, see the file marsyas/groups.doxy.

There is one special group: Basic Processing. This is a subset of the Processing group. No MarSystem should only be in the Basic group; it should be placed in both groups, with

     \ingroup Processing Basic

Code which is not a MarSystem should be placed in the Notmar group.

A complete list of groups can be found in the marsyas/groups.doxy file. The main groups are Composites, Basic, IO, Processing, Analysis, and Synthesis.