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 Gives a brief description of a function. \param Describes a specific . \return Describes the return value. \a Mark next word as a reference to a parameter. \e Use italic font for the next word. \b Use bold font for the next word. \c Use typewriter font for the next word. \sa Adds a section with crossreferences. \bug Describe a known bug. \todo Add a todo list. \attention Add a section for something that needs attention. \warning Add a section for a warning. \anchor Set an invisible anchor which can be used to create a link with /ref. \ref [] Add a link to . For a complete list of tags please read section 20 "Special commands" of the doxygen manual.