view DOCS/tech/code-documentation.txt @ 18588:bd5e0a0b89e8

(unfinished) review with lots of changes

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 these guidelines
on what and how code should be documented.


Doxygen
-------

MPlayer uses doxygen for its code documentation. It generates HTML files
which contain specially tagged comment lines from the code including
cross references. 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 globally or just locally 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, mandatory for variables which
    are set by something external, eg user parameters, file information etc)

- #define, typedefs, structs
  * all global definitions
  * all local definitions whose use is not imediatly clear by their name
    (as a rule of thumb, it's better to document too much than 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

- workarounds
 * why they are needed
 * how they work
 * what side effects they have

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 language used should be kept 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 an introduction. A very short overview follows:

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

/// This is a line used by doxygen.

/** this one, too */

/** these
here
of
course,
too */

//! this form can be also used

// This line isn't included in doxygen documentation.

/* Neither is this. */

Doxygen comments should come before the definition:

/** description */
int a_variable;

However, you can use '<' to describe things AFTER they are defined, like this:

int some_var; ///< description
#define foo(x) (x + 2) /**< returns x plus 2 */

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.