[FFmpeg-devel] [PATCH] Clarify documentation for avcodec_encode_audio

[Michael Niedermayer]

On Wed, Nov 28, 2007 at 09:55:44AM +0100, Stefano Sabatini wrote:
> On date Tuesday 2007-11-27 20:25:05 +0100, Michael Niedermayer encoded:
> > On Mon, Nov 26, 2007 at 09:46:49PM +0100, Stefano Sabatini wrote:
> > > On date Monday 2007-11-19 11:19:11 +0100, Stefano Sabatini encoded:
> > > > On date Monday 2007-11-12 09:49:24 +0100, Stefano Sabatini encoded:
> > > > > On date Sunday 2007-11-04 23:07:41 +0100, Stefano Sabatini encoded:
> > > > > > Hi all,
> > > > > > 
> > > > > > suggested log: $subject.
> > > > > > 
> > > > > > Relevant thread (ffmpeg-user):
> > > > > > http://thread.gmane.org/20070920133523.GC28112 at santefisi.caos.org
> > > > > 
> > > > > Ping.
> > > > 
> > > > New ping and patch diffed against the latest SVN.
> > > > 
> > > > Best regards.
> > > > -- 
> > > > Stefano Sabatini
> > > > Linux user number 337176 (see http://counter.li.org)
> > > 
> > > 
> > > Ping??
> > > 
> > > Please let me know if you don't care at all about documentation
> > > patches, I have so many better ways to waste my time.
> > 
> > i do care about doc patches, but i have to check the correctness of the
> > changes (which you should do but apparently dont do) so i tend to review
> > patches which have a better gain/work ratio first
> > 
> > 
> > > > Index: libavcodec/avcodec.h
> > > > ===================================================================
> > > > --- libavcodec/avcodec.h	(revision 11059)
> > > > +++ libavcodec/avcodec.h	(working copy)
> > > > @@ -2672,9 +2672,11 @@
> > > >   * @param avctx the codec context
> > > >   * @param[out] buf the output buffer
> > > >   * @param[in] buf_size the output buffer size
> > > > - * @param[in] samples the input buffer containing the samples
> > > > + * @param[in] samples the input buffer containing the samples. The
> > > > + * number of samples read from this buffer is defined in
> > > > + * avctx->frame_size.
> > 
> > the number of samples is frame_size*channels
> > also the 'The' belongs in the next line to avoid unneccesariy chnaging one
> > line
> 
> OK, but I'm also putting a "." at the end of the first line.
> 
> > > > - * @return On error a negative value is returned, on succes zero or the number
> > > > - * of bytes used from the input buffer.
> > > > + * @return On error a negative value is returned, on success zero or
> > > > + * the number of bytes used to encode the data read from \p samples.
> > > >   */
> > 
> > the original is clearer than your version
> > a "is returned" could be added to the end
> > "used" could be changed to "consumed"
> > i dont think theres a special case for 0 (like undefined num bytes consumed)
> > the typo fix belongs into a seperate patch
> > and i dont see why "the number" is moved to the next line
> 
> No, the original is plain wrong, "consumed" is not the right term
> since the returned value is the number of bytes used to *encode* the
> data read, when the number of bytes read is frame_size*channels.

right, sorry, i dont know what ive been thinking, ive somehow mixed encode
with decode ...


> 
> Anyway look if it seems more clear now, I'm also omitting to fix the
> typo.

but not the '.' typo

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

When the tyrant has disposed of foreign enemies by conquest or treaty, and
there is nothing more to fear from them, then he is always stirring up
some war or other, in order that the people may require a leader. -- Plato
-------------- 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/20071128/73f02ab2/attachment.pgp>