[FFmpeg-devel] Document AVOption struct

[Diego Biurrun]

On Sat, Jun 14, 2008 at 01:34:04AM +0200, Stefano Sabatini wrote:
> On date Sunday 2008-06-08 16:00:44 +0200, Michael Niedermayer encoded:
> > On Sat, Jun 07, 2008 at 10:49:02AM +0200, Stefano Sabatini wrote:
> > [...]
> > > --- libavcodec/opt.h	(revision 13684)
> > > +++ libavcodec/opt.h	(working copy)
> > [...]
> > > @@ -45,6 +57,12 @@
> > >   * AVOption
> > >   */
> > >  typedef struct AVOption {
> > > +    /**
> > > +     * the name of the option<br>
> > 
> > The name of the option. (The dot is significant syntax wise)
> 
> I checked again the Javadoc comments writing guidelines:
> http://java.sun.com/j2se/javadoc/writingdoccomments/
> 
> effectively they use Capitalization and "." at the end also for
> incomplete sentence, so I'm assuming that is the correct style.

It makes sense if you have an incomplete sentence followed by complete
sentences as in

>  /**
>   * @file opt.h
> - * AVOptions
> + * Defines the #AVOption system.
> + * An #AVClass context is a structure which contains <em>as the first
> + * field</em> a pointer to an #AVClass structure: for example
> + * #AVCodecContext, #AVFormatContext, #SwsContext are all #AVClass
> + * structures.<br>

for example, but not for cases like

> -    double min;
> -    double max;
> +    double min;                 ///< Minimum valid value for the option.
> +    double max;                 ///< Maximum valid value for the option.

There is no good reason to capitalize here and we do not do it in other
places.  So please write such comments without capitalization and
periods.

Diego