[Ffmpeg-devel] [RFC][PATCH]Doxygenize libavutil/fifo.h

[Michael Niedermayer]

Hi

On Mon, Feb 26, 2007 at 12:48:58PM +0100, Dujardin Bernard wrote:
[...]
> >[...]
> >  
> >> #ifndef FIFO_H
> >> #define FIFO_H
> >> 
> >>+/**
> >>+ * Circular fifo buffer.
> >>+ */
> >> typedef struct AVFifoBuffer {
> >>-    uint8_t *buffer;
> >>-    uint8_t *rptr, *wptr, *end;
> >>+    uint8_t *buffer;    ///< Begin pointer.
> >>+    uint8_t *rptr;      ///< Read pointer.
> >>+    uint8_t *wptr;      ///< Write pointer.
> >>+    uint8_t *end;       ///< End pointer.
> >>    
> >
> >these comments are completely redundant they provide no new
> >information to the reader, for external API i dont mind some extra
> >redundant comments which have the advantage of being nicely shown with
> >doxygen but for internal structs which the user has no business with
> >its not
> >
> >  
> Lets the Circular fifo buffer comment ?

comments about the implementation should be avoided in public header files
to prevent users from writing code which depends on the implementation details
such code breaks if the implementation changes
actually AVFifoBuffer should be moved away from fifo.h


[...]
> >  
> >>+ * @param *f fifo buffer.
> >>+ */
> >> void av_fifo_free(AVFifoBuffer *f);
> >>+
> >>+/**
> >>+ * Get size of a fifo *.
> >>    
> >
> >gets the size of a fifo
> >
> >similarely for the others
> >  
> Prefered 'Reads the datas'  or 'Reads the data' and similarely for the 
> others ?

you are killing the grammer nazies :)
theres no such thing like datas, singular is datum plural is data


> 
> Wait for your answer and commit another patch

that is "I will wait for ..." or "I?ll wait for ..." or
"iam waiting for ..."

you force me to learn english grammer to review your patches ;)

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

When you are offended at any man's fault, turn to yourself and study your
own failings. Then you will forget your anger. -- Epictetus
-------------- 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/4d84aad0/attachment.pgp>