DOCS/tech/code-documentation.txt

   1 Code documentation guidelines
   2 =============================
   3
   4 About this guide
   5 ----------------
   6
   7 Due to the ever increasing complexity and size of MPlayer it became quite hard
   8 to maintain the code and add new features. Part of this problem is the lack
   9 of proper documentation what the code in question does and how it is doing it.
  10 To tackle this problem every part of MPlayer should follow these guidelines
  11 on what and how code should be documented.
  12
  13
  14 Doxygen
  15 -------
  16
  17 MPlayer uses doxygen for its code documentation. It generates HTML files
  18 which contain specially tagged comment lines from the code including
  19 cross references. To generate it type `make doxygen` in the source root
  20 directory. It will generate the files in DOCS/tech/doxygen. To clear them
  21 again, you can use `make doxygen_clean`.
  22 For further information about doxygen and its sources please have a look
  23 at their website: http://doxygen.sf.net
  24
  25
  26 What should be documented?
  27 --------------------------
  28
  29 - every function, no matter whether it is globally or just locally used
  30   * what the function does
  31   * all parameters and return values of the function and their valid ranges
  32   * all side effects (to passed parameters, globals etc)
  33   * all assumptions made within the function
  34
  35 - global, file local and important variables
  36   * what it is used for
  37   * its valid range
  38   * where it is set (optional)
  39   * where validity checking is done (optional, mandatory for variables which
  40     are set by something external, e.g. user parameters, file information etc)
  41
  42 - #define, typedefs, structs
  43   * all global definitions
  44   * all local definitions whose use is not immediately clear by their name
  45     (as a rule of thumb, it's better to document too much than not enough)
  46   * all dependencies
  47
  48 - non-trivial parts of the code
  49   * tricky parts
  50   * important parts
  51   * special side effects
  52   * assumptions of the code
  53   * string operations and why they are safe
  54
  55 - workarounds
  56  * why they are needed
  57  * how they work
  58  * what side effects they have
  59
  60 If you are unsure whether a comment is needed or not, add one.
  61
  62
  63 How should it be documented?
  64 ----------------------------
  65
  66 All comments should be in correct and clear English. Any other language is
  67 not allowed. The language used should be kept simple as the code will be
  68 read mostly by non-native speakers. For function and variable documentation,
  69 a style usable by doxygen should be used. See section 3 "Documenting the code"
  70 of the doxygen manual for an introduction. A very short overview follows:
  71
  72 Doxygen includes only special comments in the documentation, those are:
  73
  74 /// This is a line used by doxygen.
  75
  76 /** this one, too */
  77
  78 /** these
  79 here
  80 of
  81 course,
  82 too */
  83
  84 //! this form can be also used
  85
  86 // This line isn't included in doxygen documentation.
  87
  88 /* Neither is this. */
  89
  90 Doxygen comments should come before the definition:
  91
  92 /** description */
  93 int a_variable;
  94
  95 However, you can use '<' to describe things AFTER they are defined, like this:
  96
  97 int some_var; ///< description
  98 #define foo(x) (x + 2) /**< returns x plus 2 */
  99
 100 There are a couple of special tags for doxygen:
 101
 102 \brief <one line text>
 103    Gives a brief description of a function.
 104 \param <parameter> <text>
 105    Describes a specific <parameter>.
 106 \return <text>
 107    Describes the return value.
 108 \a <word>
 109    Mark next word as a reference to a parameter.
 110 \e <word>
 111    Use italic font for the next word.
 112 \b <word>
 113    Use bold font for the next word.
 114 \c <word>
 115    Use typewriter font for the next word.
 116 \sa <references>
 117    Adds a section with crossreferences.
 118 \bug <text>
 119    Describe a known bug.
 120 \todo <text>
 121    Add a todo list.
 122 \attention <text>
 123    Add a section for something that needs attention.
 124 \warning <text>
 125    Add a section for a warning.
 126 \anchor <refname>
 127    Set an invisible anchor which can be used to create a link with \ref.
 128 \ref <refname> [<text>]
 129    Add a link to <refname>.
 130
 131 For a complete list of tags please read section 20 "Special commands" of the
 132 doxygen manual.