[FFmpeg-devel] Document AVOption struct

[Stefano Sabatini]

On date Monday 2008-06-16 13:25:29 +0200, Michael Niedermayer encoded:
> On Mon, Jun 16, 2008 at 10:25:12AM +0200, Stefano Sabatini wrote:
> > On date Monday 2008-06-16 04:45:50 +0200, Michael Niedermayer encoded:
> > > On Sun, Jun 15, 2008 at 07:21:59PM -0400, The Wanderer wrote:
> > > > Stefano Sabatini wrote:
> > > > 
> > > > > On date Saturday 2008-06-14 22:47:33 +0200, Michael Niedermayer
> > > > > encoded:
> > > > > 
> > > > >> On Sat, Jun 14, 2008 at 01:34:04AM +0200, Stefano Sabatini wrote:
> > > > 
> > > > >>> I tried to improve it, I think now it's simpler and clearer:
> > > > >>>     /**
> > > > >>>      * Aggregates options into a single logical unit. Named constants
> > > > >>>      * belonging to the same option share the same unit, which
> > > > >>>      * corresponds to the name of that option.
> > > > >>>      */
> > > > >> 
> > > > >> A function does something a variables is something.
> > > > >> 
> > > > >> A description of a variable should not be about how it is used but
> > > > >> about what it is primarely. After one has defined what the variable
> > > > >> is/contains one can, if needed explain what that is used for if
> > > > >> thats is important.
> > > > > 
> > > > > Got it, please check if it is better now.
> > > > 
> > > > For as much as my two cents are worth, looks good to me.
> > > 
> > > I agree from a english language point of view ...
> > > sadly it contains a bug now ;)
> > > the unit is not neccessarily the name of the option it belongs to, as example
> > > see cmp_func. The constants "belong" to several options (cmp,subcmp,...)
> > 
> > Doh!! Corrected here, also fixed the "default/the default", issue.
> > 
> > Regards.
> > -- 
> > FFmpeg = Funny Freak Maxi Portable EntanGlement
> 
> > Index: libavcodec/opt.h
> > ===================================================================
> > --- libavcodec/opt.h	(revision 13775)
> > +++ libavcodec/opt.h	(working copy)
> > @@ -25,6 +25,13 @@
> >  /**
> >   * @file opt.h
> >   * AVOptions
> > + *
> > + * An #AVClass context is a structure which contains as the first
> > + * field a pointer to an #AVClass structure, for example
> > + * #AVCodecContext, #AVFormatContext, #SwsContext.
> > + *
> > + * An #AVClass object is an #AVClass structure \e or an #AVClass
> > + * context.
> >   */
> 
> Iam still not 100% happy with this, these objects, contexts and structures
> are confusing.
> 
> the rest of the patch looks ok though

Committed the rest of the patch which doesn't mention AVClass things,
though I would like to set some of the terms to use in this file to
ease documentation/understanding.

In log.h I already defined an AVClass context structure like this:
/**
 * Describes the class of an AVClass context structure, that is an
 * arbitrary struct of which the first field is a pointer to an
 * AVClass struct (e.g. AVCodecContext, AVFormatContext etc.).
 */

So I'd say to keep the "AVClass context" term, then I can abandon the
term "AVClass object" and use instead the locution "AVClass structure
or AVClass context".

Thanks for your patience.

Regards.
-- 
FFmpeg = Fiendish and Faboulous Merciless Proud EntanGlement