TEXT   52
Code documentation guidelines
Guest on 9th February 2023 02:11:29 PM


  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.

Raw Paste

Login or Register to edit or fork this paste. It's free.