[MPlayer-dev-eng] code documentation guideline draft

[Attila Kinali]

Heyo,

I used 5 free minutes to put a code documentation guideline together.
Please review it and tell me anything you dont like or that should
be improved. 

			Attila Kinali
-------------- next part --------------
Code documentation guidelines
=============================

About this guide
----------------

Due to the ever increasing complexity and size of MPlayer it became quite hard
to maintain the code and add new features. Part of this problem is the lack
of proper documentation what the code in question does and how it is doing it.
To tackle this problem every part of MPlayer should follow this guidelines
on what and how code should be documented.


Doxygen
-------

MPlayer uses doxygen for its code documentation. It generates HTML files
which contain the specialy tagged comment lines from the code including
cross refenrences. To generate it type `make doxygen` in the source root
directory. It will generate the files in DOCS/tech/doxygen. To clear them
again, you can use `make doxygen_clean`.
For further information about doxygen and its sources please have a look
at their website: http://doxygen.sf.net


What should be documented?
--------------------------

- every function, no matter whether it is globaly or just localy used 
  * what the function does
  * all parameters and return values of the function and their valid ranges
  * all side effects (to passed parameters, globals etc)
  * all assumptions made within the function

- global, file local and important variables
  * what it is used for
  * its valid range
  * where it is set (optional)
  * where validity checking is done (optional, mandantory for variables which
    are set by something external, eg user parameters, file information etc)

- #define, typedefs, structs
  * all global definitions
  * all local definitions which use is not imediatly clear by their name
    (as a rule of thumb, it's better to document too much then not enough)
  * all dependencies

- non-trivial parts of the code
  * tricky parts
  * important parts
  * special side effects
  * assumptions of the code
  * string operations and why they are safe

If you are unsure whether a comment is needed or not, add one.


How should it be documented?
----------------------------

All comments should be in correct and clear english. Any other language is
not allowed. The used language should be also a rather simple as the code will
be read mostly by non-native speakers. For function and variable documentation, a style usable by doxygen should be used. See section 3 "Documenting the code"
of the doxygen manual for a introduction. A very short overview follows:

Doxygen includes only special comments in the documentation, those are:

/// this is line is used by doxygen

/** this one too */

/** these
here 
of
course
too */

//! this form can be also used

// this line isnt included in doxygen documentation

/* neither is this */

There are a couple of special tags for doxygen:

\brief <one line text>
   gives a brief description of a function.
\param <parameter> <text>
   describes a specific <parameter> 
\return <text>
   describes the return value
\a <word>
   mark next word as a reference to a parameter
\e <word>
   use italic font for the next word
\b <word>
   use bold font for the next word
\c <word>
   use typewriter font for the next word   
\sa <references>
   adds a section with crossreferences
\bug <text>
   describe a known bug
\todo <text>
   add a todo list
\attention <text>
   add a section for something that needs attention
\warning <text>
   add a section for a warning
\anchor <refname>
   set an invisible anchor which can be used to create a link with /ref
\ref <refname> [<text>]
   add a link to <refname>

For a complete list of tags please read section 20 "Special commands" of the
doxygen manual.