mirror of https://github.com/mpv-player/mpv
133 lines
3.9 KiB
Plaintext
133 lines
3.9 KiB
Plaintext
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, e.g. user parameters, file information etc)
|
|
|
|
- #define, typedefs, structs
|
|
* all global definitions
|
|
* all local definitions whose use is not immediately 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.
|