[FFmpeg-devel] [PATCH] Improve metadata documentation

[Stefano Sabatini]

On date Tuesday 2010-05-25 20:11:13 +0200, Cyril Russo encoded:
> Hi,
> 
>   As subjects says.
> 
> Best regards,
> Cyril RUSSO
> 
> 

> Index: libavformat/avformat.h
> ===================================================================
> --- libavformat/avformat.h      (revision 23312)
> +++ libavformat/avformat.h      (working copy)
> @@ -117,8 +117,8 @@
> 
>  #define AV_METADATA_MATCH_CASE      1
>  #define AV_METADATA_IGNORE_SUFFIX   2
> -#define AV_METADATA_DONT_STRDUP_KEY 4
> -#define AV_METADATA_DONT_STRDUP_VAL 8
> +#define AV_METADATA_DONT_STRDUP_KEY 4   ///< Don't duplicate tag key's string
> +#define AV_METADATA_DONT_STRDUP_VAL 8   ///< Don't duplicate tag value's string

"Do not" - contractions are better avoided in official docs.

>  #define AV_METADATA_DONT_OVERWRITE 16   ///< Don't overwrite existing tags.
> 
>  typedef struct {
> @@ -154,7 +154,10 @@
>   * Sets the given tag in m, overwriting an existing tag.
>   * @param key tag key to add to m (will be av_strduped depending on flags)
>   * @param value tag value to add to m (will be av_strduped depending on flags)

> + * @param flags any combination of AV_METADATA_DONT_OVERWRITE, AV_METADATA_DONT_STRDUP_KEY,
> + *              AV_METADATA_DONT_STRDUP_VAL

It's preferable to just say AV_METADATA_* flags, otherwise this will
result in macros / function docs desynchronization.

>   * @return >= 0 on success otherwise an error code <0

> + * @sa AV_METADATA_DONT_OVERWRITE

duplication

Thanks, regards.
-- 
FFmpeg = Fabulous & Fundamentalist Mystic Portable Epic Gospel