[FFmpeg-devel] [PATCH] Document av_[io]format_next() functions

[Stefano Sabatini]

On date Saturday 2009-02-14 23:27:00 +0100, Diego Biurrun encoded:
> On Sat, Feb 14, 2009 at 10:22:40PM +0100, Stefano Sabatini wrote:
> > 
> > As for the \p I have no problem at stripping them all, let's hear what
> > Diego will say.
> 
> What do they do? :)

That \p stands for "parameter", and it's used by Doxygen (maybe by
Javadoc too?) to mark the worder using a special font, to distinguish
it from the rest of the text, check our doxygen HTML docs if you care
to see with your eyes how it is rendered.

So it basically makes slightly worse the plain text documentation
readability while it slightly improves the HTML/LaTeX output
readability, but in some circumstances may help to improve readability
of the plain text as well:

Puts in the buffer \p out the content of \p in.
vs.
Puts in the buffer out the content of in.

making more clear that a word denotes a parameter.

AFAIR in FFmpeg it is used only in some files, namely avcodec.h, in
swscale.h and somewhere in libavutil (mem.h, base64.h), sparsely in
some function of lavfi.

No strong opinion for it, so I leave the choice to Diego if it has to
be considered the "official" FFmpeg documentation style or not.
 
> I must shamefully admit that I have not dealt much with Doxygen so far..
> 
> > --- libavformat/avformat.h	(revision 17277)
> > +++ libavformat/avformat.h	(working copy)
> > @@ -687,7 +687,18 @@
> >  
> > +/**
> > + * If f is NULL returns the first registered input format,
> 
> NULL,
> 
> > + * if f is non-NULL returns the registered input format next after f,
> 
> if f is non-NULL, returns the next registered input format after f,
> 
> > +/**
> > + * If f is NULL returns the first registered output format,
> > + * if f is non-NULL returns the registered output format next after f,
> > + * or NULL if f is the last one.
> 
> same as above

Fixed and stripped the \p's for consistency with the rest of the file.

Regards.
-- 
FFmpeg = Frightening and Frenzy Mean Pitiless Erroneous Gangster
-------------- next part --------------
A non-text attachment was scrubbed...
Name: document-av-ioformat-next.patch
Type: text/x-diff
Size: 779 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090215/84760af6/attachment.patch>