[FFmpeg-devel] [PATCH] Doxygenate libavutil/mem.h

[Michael Niedermayer]

On Thu, Nov 01, 2007 at 03:31:40PM +0100, Stefano Sabatini wrote:
> On date Saturday 2007-10-20 11:55:48 +0200, Stefano Sabatini encoded:
> > On date Thursday 2007-10-18 12:12:51 +0200, Stefano Sabatini encoded:
> > > On date Tuesday 2007-10-16 01:08:26 +0200, Diego Biurrun encoded:
> > > > On Mon, Oct 15, 2007 at 07:42:19PM +0200, Michael Niedermayer wrote:
> > [...]
> > > > > patch rejected it mixes too many unrelated changes
> > > > > some pure spelling corrections some plain wrong
> > > > 
> > > > I went over the file and fixed a couple of grammar and spelling
> > > > mistakes.  Please send in the rest of your changes now.
> > > 
> > > Hi Diego,
> > > 
> > > I noticed you changed:
> > > 
> > >  * Duplicates the string \p s.
> > >             ^
> > > to: 
> > > 
> > >  * Duplicate the string \p s.
> > > 
> > > (in all my previous documentation patches I used the first form).
> > > 
> > > Please can you say which form you prefer, I really don't mind about
> > > it, I just want it to be globally consistent.
> > > 
> > > Also a note in the programming style doc section regarding this would
> > > be nice.
> > 
> > New patch attached.
> > 
> > I removed the notes telling:
> >  * @note av_mallocz(0) return value is actually undefined, but future
> >  * versions might force it to be a non-NULL value.
> > 
> > which maybe deserve another patch or are simply unappropriate, and
> > applied consistently the "Duplicate" style (I'll eventually send
> > another patch to "third-personify" the documentation).
> > 
> > I checked again the implmentation and I saw how it depends on the
> > various malloc/free/realloc defined by the C library, which are
> > somehow depending on the implementation, so I cannot be sure the
> > documentation is perfectly coherent in case of a misbehaving
> > implementation.
> > 
> > I think however that some partially wrong documentation is still
> > better than none at all, if you can find some way to make it more
> > generic and indipendent on the underlying implementation please
> > suggest how to do it.
> [...]
> 
> New try, some cosmetic changes of the previous version gone into
> another patch, small rework of av_realloc docs.
> 
> Regards
> -- 
> Stefano Sabatini
> Linux user number 337176 (see http://counter.li.org)

> Index: libavutil/mem.h
> ===================================================================
> --- libavutil/mem.h	(revision 10893)
> +++ libavutil/mem.h	(working copy)
> @@ -33,16 +33,24 @@
>  #endif
>  
>  /**
> - * Memory allocation of size bytes with alignment suitable for all
> - * memory accesses (including vectors if available on the
> - * CPU). av_malloc(0) must return a non-NULL pointer.
> + * Allocate a block of \p size bytes with alignment suitable for all
> + * memory accesses (including vectors if available on the CPU).
> + * @param size Size of the block to be allocated.

size in bytes


> + * @return Pointer to the allocated block, NULL if it cannot allocate
> + * it.
> + * @see av_mallocz()
>   */
>  void *av_malloc(unsigned int size);
>  
>  /**
> - * av_realloc semantics (same as glibc): If ptr is NULL and size > 0,
> - * identical to malloc(size). If size is zero, it is identical to
> - * free(ptr) and NULL is returned.
> + * Allocate or reallocate a block of memory.
> + * If \p ptr is NULL and \p size > 0, allocate a new block. If \p
> + * size is zero, free the memory block pointed by \p ptr.
> + * @param size New size for the block to be allocated or reallocated.

> + * @param ptr Pointer to an already allocated memory block or NULL.

wrong av_realloc(malloc(5), 0) is not valid


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

While the State exists there can be no freedom; when there is freedom there
will be no State. -- Vladimir Lenin
-------------- 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/20071101/382eeed8/attachment.pgp>