[FFmpeg-cvslog] r23983 - trunk/libavcodec/h264.c

[Reimar Döffinger]

On Wed, Jul 14, 2010 at 10:56:43PM +0200, Diego Biurrun wrote:
> On Fri, Jul 09, 2010 at 03:28:20PM +0200, Michael Niedermayer wrote:
> > On Fri, Jul 09, 2010 at 09:03:44AM +0200, Diego Biurrun wrote:
> > > On Thu, Jul 08, 2010 at 09:05:42PM +0200, Reimar D?ffinger wrote:
> > > > On Thu, Jul 08, 2010 at 06:48:58PM +0100, M?ns Rullg?rd wrote:
> > > > > Michael Niedermayer <michaelni at gmx.at> writes:
> > > > > 
> > > > > > On Thu, Jul 08, 2010 at 06:30:58PM +0100, M?ns Rullg?rd wrote:
> > > > > >> Michael Niedermayer <michaelni at gmx.at> writes:
> > > > > >> 
> > > > > >> > lets assume the variable was named var0 instead of field
> > > > > >> > what was written there was:
> > > > > >> > @param field, 0/1 initialize the weight for interlaced MBAFF -1 initializes the rest
> > > > > >> >
> > > > > >> > what should have been written there (in that case) would have been:
> > > > > >> > @param var0 field, 0/1 initialize the weight for interlaced MBAFF -1 initializes the rest
> > > > > >> 
> > > > > >> Still takes me quite some effort to decipher.
> > > > > >
> > > > > > so how would you say it then?
> > > > > 
> > > > > I don't know since I still haven't figured out exactly what it's
> > > > > trying to say.
> > > > 
> > > > I guess it is
> > > > "indicates the field number (0 or 1) for interlaced MBAFF. -1 is used for the non-interlaced case."
> > > > Of course this is just a guess...
> > > 
> > > Michael, is that a better description?
> > 
> > no, its wrong
> > -1 is not limited to non interlaced, dont forget that in h264 there are
> > multiple forms of interlacing.

Well, strictly speaking I didn't say anything about PAFF, so if that's
all my description was only incomplete, not wrong.

> @param field A value of 0 or 1 indicates the field number for
>              interlaced MBAFF, -1 indicates the other cases.

I very much object to making the documentation a guessing-game.
At least make it "indicates the other cases (PAFF and progressive)",
assuming this is correct.
But saying "other cases" when it is obviously non-obvious which those
are is only useful if your goal is to drive anyone away who doesn't
already know the code inside-out.