- 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.
Raw Paste