[Clam-devel] documentation

[Pau Arumi]

En/na Greg Kellum ha escrit:
> 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:

yes, using doxygen tags as you show is the way to go, when needed.
specially needed for things we consider _user api_. other things
are more internal and more likely to change. so very brief doc is
preferred. of course, _naming_ (class, methods, but also vars) is
the most important source of documentation. and it tends to be
up-to-date with the code ;). at least imho.

the runtime visible doc is another story --not doxygen-- but
metadata information in the factory or in ports/controls
constructor. we'll do a proposal on how to do it when ready.
however taking the doxygen strings from the source file is an
option to evaluate...

pau



> /***************************************************/
> /*! \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 <mailto: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
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> Clam-devel mailing list
> Clam-devel at llistes.projectes.lafarga.org
> https://llistes.projectes.lafarga.org/cgi-bin/mailman/listinfo/clam-devel