[FFmpeg-devel] [RFC] scenechange_score in AVCodecContext?

[Stefano Sabatini]

On date Wednesday 2007-11-14 10:55:21 +0100, Diego Biurrun encoded:
> On Wed, Nov 14, 2007 at 09:47:10AM +0100, Stefano Sabatini wrote:
> > On date Tuesday 2007-11-13 17:39:34 +0100, Diego Biurrun encoded:
> > > On Tue, Nov 13, 2007 at 04:14:22PM +0100, Stefano Sabatini wrote:
> > > > 
> > > > --- libavcodec/avcodec.h	(revision 11006)
> > > > +++ libavcodec/avcodec.h	(working copy)
> > > > @@ -1671,6 +1671,15 @@
> > > >  
> > > >      /**
> > > > +     * scene change score
> > > > +     * measure the degree of changement between the current and the
> > > 
> > > Capitalize, "changement" is not an English word, just use "change".
> > 
> > Fixed.
> > 
> > Diego please could you define somewhere (for example in
> > doc/general.texi:Coding Rules) the style to be used for the
> > documentation, so that I don't have every time to figure out which is
> > the correct style to adopt?
> 
> Correct English?  I'm not sure what you would want me to write in
> there..

I was referring to the Capitalization style (and yes I know I still
have to improve my English).

I'd like for example something like this:

The documentation style used should be preferably consistent with the
following examples (no matter if the rest of the documentation of the
file you're writing into is not compliant with this).

Function definitions:
/**
 * Set the color for the shed of the bike defined by the \p bike_ctx.
 *
 * @param bike_ctx Context of the bike to be setted. 
 * @param shed_color Integer representing the color to set for the \p 
 * \p bike_ctx.
 * @return 0 if the shed color has been successfully setted, a
 * negative value otherwise.
 */
int avbike_set_shed_color (AVBikeContext *bike_ctx, int shed_color);
 
Field definitions:
/** 
 * Represent the shed color.
 * Values should be choosen between 0 and AV_BIKE_COLORS_NB.
 * - encoding: unusued
 * - decoding: Set by libavride.
 *
 * @warning An inadequate and not carefully considered choice for this
 * field will result in a terrible and unexpected crash of the bike
 * riding process.
 * @see avbike_color_string()
 */ 
int shed_color;

Note that we are using "Represent" rather than "Represents".

Documentation should be as generic as possible, and not dependant on
the definition of external API, and possibly not redundant.

Also the lenght of each line should be possibly not greater than 75
columns.

Best regards.
-- 
Stefano Sabatini
Linux user number 337176 (see http://counter.li.org)