Mercurial > mplayer.hg
comparison DOCS/tech/code-documentation.txt @ 13290:fb8f8882fb6a
adding the code documentation guide lines
now everyone has to follow them
author | attila |
---|---|
date | Thu, 09 Sep 2004 01:13:26 +0000 |
parents | |
children | 05d3254e05b1 |
comparison
equal
deleted
inserted
replaced
13289:2cb80075204c | 13290:fb8f8882fb6a |
---|---|
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 the 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, eg user parameters, file information etc) | |
41 | |
42 - #define, typedefs, structs | |
43 * all global definitions | |
44 * all local definitions whos use is not imediatly clear by their name | |
45 (as a rule of thumb, it's better to document too much then 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 There are a couple of special tags for doxygen: | |
91 | |
92 \brief <one line text> | |
93 Gives a brief description of a function. | |
94 \param <parameter> <text> | |
95 Describes a specific <parameter>. | |
96 \return <text> | |
97 Describes the return value. | |
98 \a <word> | |
99 Mark next word as a reference to a parameter. | |
100 \e <word> | |
101 Use italic font for the next word. | |
102 \b <word> | |
103 Use bold font for the next word. | |
104 \c <word> | |
105 Use typewriter font for the next word. | |
106 \sa <references> | |
107 Adds a section with crossreferences. | |
108 \bug <text> | |
109 Describe a known bug. | |
110 \todo <text> | |
111 Add a todo list. | |
112 \attention <text> | |
113 Add a section for something that needs attention. | |
114 \warning <text> | |
115 Add a section for a warning. | |
116 \anchor <refname> | |
117 Set an invisible anchor which can be used to create a link with /ref. | |
118 \ref <refname> [<text>] | |
119 Add a link to <refname>. | |
120 | |
121 For a complete list of tags please read section 20 "Special commands" of the | |
122 doxygen manual. | |
123 | |
124 |