[FFmpeg-devel] [PATCH] Improve metadata documentation

[Aurelien Jacobs]

On Wed, May 26, 2010 at 09:31:33AM +0200, Cyril Russo wrote:
> Le 26/05/2010 01:05, Stefano Sabatini a ?crit :
> >
> >"Do not" - contractions are better avoided in official docs.
> Done. Changed existing "don't" to "Do not" too.
> >>  #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.
> >
> Done.
> >>   * @return>= 0 on success otherwise an error code<0
> >>+ * @sa AV_METADATA_DONT_OVERWRITE
> >duplication
> I've kept it because it'll generate a link (while AV_METADATA_*
> won't), so it's easier for documentation navigation.
> Cheers,
> Cyril RUSSO

> Index: libavformat/avformat.h
> ===================================================================
> --- libavformat/avformat.h      (revision 23312)
> +++ libavformat/avformat.h      (working copy)
> @@ -117,9 +117,9 @@
> 
>  #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_OVERWRITE 16   ///< Don't overwrite existing tags.
> +#define AV_METADATA_DONT_STRDUP_KEY 4   ///< Do not duplicate tag key's string.
> +#define AV_METADATA_DONT_STRDUP_VAL 8   ///< Do not duplicate tag value's string.

To any C developer, "strdup" has a very clear and precise meaning. On the
other hand, "duplicate" don't have any defined meaning to me (does it
mean transform "author" into "authorauthor" ?).
So those 2 comments are just adding confusion to flags which otherwise
have a very clear meaning by themself.

Aurel