Re: [fluid-dev] Some guidelines for FluidSynth development

[Pedro Lopez-Cabanillas]

On Monday, April 27, 2009, address@hidden wrote:
> Looking at the recent commits, I thought it would be good to mention
> some general guidelines.
>
> Please make use of the ChangeLog.  Change details don't have to be
> incredibly detailed and in fact more general descriptions are better,
> since the details are in the code itself.

I'm sorry for not doing it sometimes.

> Doxygen comments should be put in the .c source files above the
> definition which they describe, not in the headers.  A TODO item is to
> move the existing documentation into the C code.

Except doxygen comments for types, constants, enums,... that are defined only 
in the headers. A brief file description may be also be included for each 
header. I'm thinking about defining doxygen modules (tags for grouping things 
together) also within headers and source files.

> We need to come up with some standard way to indicate in Doxygen
> documentation that an API is from a specific version of FluidSynth and
> make use of it.  Perhaps something like:
>
> /**
>   * Create a new file renderer and open the file.
>   * @param synth The synth that creates audio data.
>   * @param filename Output filename
>   * @param period_size Sample count, amount of samples to write to the file
> at * every call to fluid_file_renderer_process_block().
>   * @return the new object, or NULL on failure
>   *
>   * Optional more descriptive message here..
>   *
>   * API: 1.1.0
>   */
>
> Can't think of anything else at the moment.  Great to see the sample
> renderer and player code committed.  Some nice new functionality which
> I should actually start using :)
>
>       Josh

Please add DOCME tags whenever you find poorly, unclear or undefined items. 
There are already a buch of them (about 30). If you find one which you can 
fix, please do it!

I'm going to (slowly) add comments where I'm proficient (MIDI related things).
  
Regards,
Pedro