[FFmpeg-devel] [PATCH] Document libavcodec/opt.h

[Diego Biurrun]

On Fri, Jun 06, 2008 at 01:08:57AM +0200, Stefano Sabatini wrote:
> 
> some cosmetics and other minor improvements, also thanks to Michael it
> includes now a more complete explanation of av_set_string().
> 
> In the case this will be applied, I think should be also a good idea
> to update the opt.c definitions to match the parameter names I used in
> this patch.

Just make a patch for this :)

> --- libavcodec/opt.h	(revision 13667)
> +++ libavcodec/opt.h	(working copy)
> @@ -45,19 +57,36 @@
>  typedef struct AVOption {
> +    /**
> +     * the name of the option, it should be unique amongst the options
> +     * contained in an AVClass object<br>

Capitalize, end in a period.

> -     * short English text help.
> +     * short English text help

help text

> -     * @todo what about other languages
> +     * @todo what about other languages?

Capitalize.

These two hunks I committed separately.

> +     * the offset to context structure where the option value should
> +     * be stored, it is 0 if the structure is used to contain a named
> +     * value

Capitalize, end in a period.

There are more cases, please review your patch for these changes.

> @@ -67,22 +96,172 @@
>  #define AV_OPT_FLAG_VIDEO_PARAM     16
>  #define AV_OPT_FLAG_SUBTITLE_PARAM  32
>  //FIXME think about enc-audio, ... style flags
> +
> +    /**
> +     * aggregates options into a single logic unit (for example named

capitalize, s/logic/logical/

> +     * values for a flag or an int), if the option contains a named

Split this long sentence in two at the comma.

> + * @return a pointer to the first option found or NULL if cannot find
> + * any option matching the parameters

This sentence is lacking a subject and thus does not make sense.

> + * @param[in] name the name of the option to be looked for

to look for, same below

> + * optionally with a SI postfix or a named scalar. Behaviour with +-

BehaviOr, please use American English.

> + * @param[in,out] o_out if non NULL puts at this address the pointer
> + * to the first option found in \p ctx with name \p name

non-NULL

.. put the pointer .. at this address

> + * @param[in] buf the buffer used for returning non string values as

non-string

> + * Shows an header telling the AVClass of \p obj then lists all

a

> + * @param[in]  av_log_ctx a pointer to a context which is used for logging the output

nit: odd spacing

> + * Sets the default values for the options in \p ctx.  Default values

The default is one space after periods around here.

Diego