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

[Stefano Sabatini]

On date Wednesday 2007-11-14 12:28:24 +0100, Michael Niedermayer encoded:
> On Wed, Nov 14, 2007 at 11:57:41AM +0100, Stefano Sabatini wrote:
> > 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:
[...]
> > > > 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).
> 
> http://java.sun.com/j2se/javadoc/writingdoccomments/
> 
> yes i know its ugh vomit java ...
> but its better than writing a vastly worse style recommandition

Oh my god I never noticed this:

"Comments: Use the JavaDoc/Doxygen
format (see examples below) so that code documentation
can be generated automatically."

in doc/general.texi!

Anyway a more explicit example would be nice.

> [...]
> > 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".
> 
> yes i know and this is bad it should be *s i dunno what idiot wrote the
> comments without ...

>From the mentioned document:

"Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person imperative.
      Gets the label. 	      (preferred)
      Get the label. 	      (avoid)"

So should us prefer the third person form?

> also in above case it should be 
> /**
>  * The shed color.
> 
> and no should, but rather
> Values must be >= 0 and < AV_BIKE_COLORS_NB
> 
> also avoid the between without specifying if its inclusive/exclusive of the
> end points

Well, if it's OK I can write a small patch to clarify all these points
(and discuss it into another thread).

But this is also going astray from the original issue of the thread,
so please could you comment about the attached patch?

Thanks for your time and attention.
Best regards.
-- 
Stefano Sabatini
Linux user number 337176 (see http://counter.li.org)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: define-scenechange-score-in-avctx-02.patch
Type: text/x-diff
Size: 2205 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20071114/291f689a/attachment.patch>