[FFmpeg-devel] [PATCH] More documentation for avcodec.h

Michael Niedermayer michaelni
Tue Dec 11 12:31:04 CET 2007


On Mon, Dec 10, 2007 at 05:40:49PM +0100, Stefano Sabatini wrote:
> Hi to all ffmpeg developers,
> 
> does $subject.
> 
> For what regards the style, I'm just trying to follow the
> *predominant* style of the avcodec.h file.
> 
> I'm planning to add more documentation, especially regarding the
> bitstream filters functions and the get/reget/release-buffer
> stuff.
> 
> Regards.
> -- 
> Stefano Sabatini
> Linux user number 337176 (see http://counter.li.org)

> Index: libavcodec/avcodec.h
> ===================================================================
> --- libavcodec/avcodec.h	(revision 11200)
> +++ libavcodec/avcodec.h	(working copy)
> @@ -2330,10 +2330,53 @@
>   * @return Image data size in bytes
>   */
>  int avpicture_get_size(int pix_fmt, int width, int height);
> +
> +/**
> + * Writes in \p h_shift and \p v_shift the chroma shift values corresponding
> + * to a pixel format.
> + *
> + * @param[in] pix_fmt a pixel format code
> + * @param[in,out] h_shift a pointer to write into the horizontal chroma
> + * shift value for the pixel format
> + * @param[in,out] v_shift a pointer to write into the vertical chroma
> + * shift value for the pixel format
> + * @see PixFmtInfo
> + */
>  void avcodec_get_chroma_sub_sample(int pix_fmt, int *h_shift, int *v_shift);

no, could you please stop sending patches which "document" 1:1 what is
already obvious from the function and variable names
and then even 1:1 duplicating ALL mistakes and bugs from these
there is NO shift in there except in the variable name you duplicated that

this is NOT documentation this is a waste of space and even worse its
misleading and confusing
what is documentation is to explain WHAT a function does and what meaning
the variables have, not writing the long form of the abbreviations there

patch rejected

1. read the code
2. understand the code
3. and after successfully doing 1. and 2. docuement the API


[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

There will always be a question for which you do not know the correct awnser.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20071211/4b02e226/attachment.pgp>



More information about the ffmpeg-devel mailing list