[FFmpeg-devel] [PATCH] Document opt.h:av_set_string functions

[Stefano Sabatini]

On date Wednesday 2008-07-23 23:44:27 +0200, Stefano Sabatini encoded:
> On date Wednesday 2008-07-23 10:20:51 +0200, Diego Biurrun encoded:
> > On Tue, Jul 22, 2008 at 02:15:05AM +0200, Stefano Sabatini wrote:
> > > On date Monday 2008-07-21 19:09:42 -0400, The Wanderer encoded:
> > > > 
> > > > Also, as long as I'm glancing over the entire patch rather than just
> > > > someone else's quote of it: there should be a comma before the " or
> > > > NULL" in the return-value explanation.
> > > 
> > > Yes, also more consistent with av_find_opt() docs (but not with the rest
> > > of the FFmpeg doxygenation!!!, I hope this won't end up in a Comma
> > > Holy War, so I leave the final decision to Diego). 
> > 
> > Yes, there should be a comma.
> > 
> > > --- libavcodec/opt.h	(revision 14329)
> > > +++ libavcodec/opt.h	(working copy)
> > > @@ -99,10 +99,30 @@
> > >  
> > > + * @param[in] obj a struct whose first element is a pointer to an
> > > + * AVClass
> > 
> > This is a complete sentence.
> 
> It depends on what you mean with complete sentence, e.g.:
> a dog
> 
> we agree that it isn't a complete sentence, but for:
> a dog, which is a barking animal
> 
> I still consider it an incomplete sentence, since the subject "dog"
> doesn't have a corresponding verb.
> 
> Fixed anyway (although inconsistent with the capitalization rule
> applied for the av_find_opt() doxy).
> 
> > > + * @param[in] name the name of the field to set
> > > + * @param[in] val The value to set. If the field is not of a string
> > > + * type, then the given string is parsed.
> > 
> > For one param you capitalize, for one you do not.
> 
> This is a style issue never resolved, see for example:
> http://thread.gmane.org/20080607084902.GA13803 at geppetto
> 
> but I think I did it right, since "it is an incomplete sentence
> followed by a complete sentence".
[...]

> Index: libavcodec/opt.h
> ===================================================================
> --- libavcodec/opt.h	(revision 14344)
> +++ libavcodec/opt.h	(working copy)
> @@ -99,10 +99,30 @@
>   */
>  const AVOption *av_find_opt(void *obj, const char *name, const char *unit, int mask, int flags);
>  
> +/**
> + * @see av_set_string2()
> + */
>  attribute_deprecated const AVOption *av_set_string(void *obj, const char *name, const char *val);
>  
>  /**
>   * Sets the field of obj with the given name to value.
> + *
> + * @param[in] obj A struct whose first element is a pointer to an
> + * AVClass.
> + * @param[in] name the name of the field to set
> + * @param[in] val The value to set. If the field is not of a string
> + * type, then the given string is parsed.
> + * SI postfixes and some named scalars are supported.
> + * If the field is of a numeric type, it has to be a numeric or named
> + * scalar. Behavior with more than one scalar and +- infix operators
> + * is undefined.
> + * If the field is of a flags type, it has to be a sequence of numeric
> + * scalars or named flags separated by '+' or '-'. Prefixing a flag
> + * with '+' causes it to be set without affecting the other flags;
> + * similarly, '-' unsets a flag.
> + * @return a pointer to the AVOption corresponding to the field set or
> + * NULL if no matching AVOption exists, or if the value \p val is not
> + * valid
>   * @param alloc when 1 then the old value will be av_freed() and the
>   *                     new av_strduped()
>   *              when 0 then no av_free() nor av_strdup() will be used

Diego, is it OK to apply?

If no other objections will be cast I'll apply it in two days, then
feel free to fix it as you prefer.

Regards.
-- 
FFmpeg = Foolish & Free Merciful Picky Experimenting Genius