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

[Michael Niedermayer]

Hi

On Sat, Sep 22, 2007 at 11:46:10AM +0200, Stefano Sabatini wrote:
> On date Friday 2007-09-21 15:02:05 -0400, Rich Felker encoded:
> > On Fri, Sep 21, 2007 at 08:53:37PM +0300, Uoti Urpala wrote:
> > > On Fri, 2007-09-21 at 19:06 +0200, Stefano Sabatini wrote:
> > > > On date Friday 2007-09-21 08:18:45 -0400, Rich Felker encoded:
> > > > > On Fri, Sep 21, 2007 at 11:33:14AM +0200, Diego Biurrun wrote:
> > > > > > > + * Allocates or reallocates a block of memory.
> > > > > > > + * Same semantics as glibc realloc: if \p ptr is NULL and \p size > 0,
> > > > > > > + * identical to malloc(size). If \p size is zero, it is identical to
> > > > > > >   * free(ptr) and NULL is returned.
> > > > > 
> > > > > It would be better to cite a well-known standard, ANSI/ISO C, rather
> > > > > than glibc.... Realloc semantics are not glibc-specific.
> > > > 
> > > > Good point, changed "glibc" to "ANSI/ISO C".
> > > 
> > > ANSI/ISO C does not guarantee these semantics. A size-0 realloc need not
> > > return NULL.
> > 
> > Oh, sorry, I was looking at only half of it, the free behavior. You're
> > right, ANSI/ISO C allows returning a unique pointer that's utterly
> > useless. However, doesn't glibc actually take this second brain-dead
> > option? I know glibc's malloc returns a non-NULL value for
> > malloc(0)... not sure what realloc does.
> 
> #include <stdlib.h>
> #include <stdio.h>
> 
> /* test the behaviour of glibc realloc */
> 
> int main (void) {
> 
>     int *ptr;
>     /* allocate */
>     ptr = realloc (NULL, 100);
>     printf ("realloc(NULL, 100) is: %d\n", ptr);
> 
>     ptr = realloc (ptr, 0);
>     printf ("realloc(ptr, 0) is: %d\n", ptr);
> 
>     ptr = realloc (NULL, 0);
>     printf ("realloc(NULL, 0) is: %d\n", ptr);
> 
>     return 0;
> }
> 
> make realloc; and realloc
> cc     realloc.c   -o realloc
> realloc(NULL, 100) is: 134520840
> realloc(ptr, 0) is: 0
> realloc(NULL, 0) is: 134520840
> 
> The latter behaviour is not explicitely documented in the glibc
> manual, but it is the more obvious one (always returns a non-NULL
> pointer if it can allocate memory).
> 
> Changing realloc with av_realloc issues the same result. 
> 
> And I reverted the previous change, so now it is stated:
> "same semantics as glibc realloc"

rejected!

ive said it in the past and i say it again, the doxygen comments in teh
headers document the API they do NOT document the implementation behavior

this is not a little cosmetic issue, if you say X there it means we must
do X unless we bump the major version number
simply saying we do what implementation Y does is sick, what if 2 versions
of Y do something else? what if Y violates the c spec?

please DO NOT document what the current implementation does in the
headers this is INAPPROPRIATE!
document what it should do if its free of bugs and do it in the most
generic way possible

for example:
wrong:
@param datestr String representing a date or a duration.
- If a date the syntax is:
[{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}

correct:
@param datestr String representing a date or a duration.
parse_date supports various forms currently supported is:
[{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}
future versions might add further variants

[...]
-- 
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/20070922/b2a4e2da/attachment.pgp>