[Clam-devel] documentation

[Greg Kellum]

Hi,

With regards to the recent discussion on documentation, I have a couple of
concrete suggestions of things we might do.  One is we should stop the
problem from getting any worse than it is by making a rule that no code
should be checked into the repository without documentation.  Ideally, one
would have someone review each commit, but I don't think anyone in this
project would have the time for that.  But nonetheless, if someone notices
that someone else checked in something significant without documentation, I
think it should be considered fair to roll back the commit until they've
documented what they've done, especially if it's a commit to the CLAM
library.

Does anyone have any thoughts on what documentation conventions would
ideally be followed?  Pau you mentioned that code documentation will soon be
shown automatically in the NetworkEditor.  So, you'll probably have
something to say about how it should be formatted....  But nonetheless, I
would suggest something along the following lines:

/***************************************************/
/*! \class SomeClass
    \brief SomeClass implements waveguide modeling.

    This class uses banded waveguide techniques to
    model a variety of sounds, including bowed
    bars, glasses, and bowls.  For more
    information, see Essl, G. and Cook, P. "Banded
    Waveguides: Towards Physical Modelling of Bar
    Percussion Instruments", Proceedings of the
    1999 International Computer Music Conference.

    \author John Smith [jsmith at someurl.edu] 08/10/2007
    \since CLAM v1.2

*/
/***************************************************/
class SomeClass
{
 public:
  //! Class constructor.
  SomeClass();

  //! Class destructor.
  ~SomeClass();

  /**
   *  Non-supervised Do method.  Produces as output the synthesized audio
   *  for the waveguide model.
   *
   *  \param position - strike position [0 - 1]
   *  \param amplitude - amplitude of the strike [0-1]
   *  \param out - the outgoing audio synthesized from the given parameters
   *
   *  \exception throws an IllegalArgumentException if the parameter values
are out of their allowed range
   */
  void Do(SomeType position, SomeType amplitude, Audio& out)

};

Best,
Greg
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.clam-project.org/pipermail/clam-devel-clam-project.org/attachments/20070810/935adbca/attachment-0002.htm>