[Ffmpeg-devel] [PATCH]Update Doxygen comments for libavutil/tree.h

Michael Niedermayer michaelni
Mon Feb 26 15:07:07 CET 2007


Hi

On Mon, Feb 26, 2007 at 11:49:50AM +0100, Dujardin Bernard wrote:
> Diego Biurrun a ?crit :
> >>? patch abstract of referenced post
> >>+ * if a insertion happened, then either key or NULL is returned (that
> >>+ * depends of the tree state and the implementation, you should make no
> >>+ * assumptions that its one or the other in the code)
> >>    
> >
> >its --> it is or it's
> >
> >"its" is a possessive pronoun, just like "my" or "your" "his/her".  As a
> >rule of thumb if you can replace "its" in a sentence by "his/her" and it
> >still makes sense (apart from the changed gender), then you must use
> >"its", if it does not, then you must use "it's/it is".
> >
> >For example:
> >
> >OK:
> >The dog wagged its tail.  -->  The dog wagged his/her tail.
> >
> >Nonsense:
> >It is a shame.  -->  His/her a shame.
> >
> >Does that clear things up?
> >  
> Sorry, I have no pay attention to this "its"
> Patch attached (tree.c also)
> 
> Bernard

> Index: tree.c
> ===================================================================
> --- tree.c	(revision 8131)
> +++ tree.c	(working copy)
> @@ -18,6 +18,12 @@
>   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>   */
>  
> +/**
> + * @file tree.c
> + * A tree container implementation.
> + * @author Michael Niedermayer <michaelni at gmx.at>
> + */
> +
>  #include "common.h"
>  #include "log.h"
>  #include "tree.h"

> Index: tree.h
> ===================================================================
> --- tree.h	(revision 8131)
> +++ tree.h	(working copy)
> @@ -18,6 +18,13 @@
>   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>   */
>  
> +
> +/**
> + * @file tree.h
> + * A tree container implementation.

s/implementation//
theres no specific implementation in the header and emphasizing that for
the c file also does nothing good


> + * @author Michael Niedermayer <michaelni at gmx.at>
> + */
> + 
>  #ifndef TREE_H
>  #define TREE_H
>  
> @@ -42,11 +49,16 @@
>   *              keep the tree balanced
>   *
>   * @return if no insertion happened, the found element
> - *         if a insertion happened, then either key or NULL is returned (which it is
> - *         depends on the tree state and the implemenattion, you should make no
> - *         asumtations that its one or the other in code)
> + *         if a insertion happened, then either key or NULL is returned (that
> + *         depends of the tree state and the implementation, you should make no
> + *         assumptions that it is one or the other in the code)
>   */

"of" sounds wrong
and i think its "an insertion"


>  void *av_tree_insert(struct AVTreeNode **rootp, void *key, int (*cmp)(void *key, const void *b));
> +
> +/**
> + * Destroy a node and node's childs.
> + * @param t a pointer to the node.
> + */
>  void av_tree_destroy(struct AVTreeNode *t);

not good, no comment is better then half wrong comments, what you
write is as if i could call this with any node and it would delete
its immedeate children or the whole branch neither is true it would
crash your application if used like that

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

Many that live deserve death. And some that die deserve life. Can you give
it to them? Then do not be too eager to deal out death in judgement. For
even the very wise cannot see all ends. -- Gandalf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20070226/998cfc74/attachment.pgp>



More information about the ffmpeg-devel mailing list