[MPlayer-dev-eng] important: doxygen - documenting the source - change of code policy

[Attila Kinali]

On Mon, Aug 09, 2004 at 10:29:59PM +0200, Reimar Döffinger wrote:
> Hi,
> 
> >**** IMPORTANT *****
> >As with the inclusion of this patch, i also want to make a change in
> >code policy, namely that every function/variable/whatever should be
> >documented in a way that doxygen can make use of it.
> 
> That would have to go into patches.txt, and I personally need an 
> explantation of "in a way that doxygen can make use of it". And no, I'm 
> not motivated to read its docs.
> 
> >This poll will be open until 2004-08-22T00:00+0200 or until there
> >are 10 votes for either yes or no (ie most of the active developers
> >voted for one side).
> 
> I'll vote for yes if I get an introduction to "commenting for doxygen" 
> in exchange ;-)

Sure,

The basic usage is this that you use a form of a comment that one
wouldnt normaly use to tell doxygen that it should process it.
thos are:
/// instead of //
//! instead of //

/** ... */ instead of /* */
etc pp (have a look at the section about comments in the doxygen docu)

There are a few special command which you can (and should) use:
\brief which adds a brief description. Should be short of course. Needs
an empty line after wards as a delimter to the rest (iirc). After it a
long description of the function can (and sometimes should) follow.

\param <param> <desc> adds a description of a parameter

\return describes the return value

after these again a long desc may follow


doxygen allows a lot more optinons, even html style enumerations/lists
For a full liste have a look at the docu.
For a short intro have a look at libmpdvdkit2/libdvdcss.c

			Attila Kinali