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

[Diego Biurrun]

On Sun, Feb 15, 2009 at 12:11:30AM +0100, Stefano Sabatini wrote:
> 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.

OK

> 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 have no strong opinion.  It depends on whether the Doxygen docs are
used in their compiled or plaintext forms.  But in principle more
markup is generally a good thing.

Diego