Mercurial > mplayer.hg
annotate DOCS/tech/code-documentation.txt @ 36334:c1033e9288b1
Extract audio encoding code into a separate helper function.
author | reimar |
---|---|
date | Sun, 25 Aug 2013 11:30:43 +0000 |
parents | 32725ca88fed |
children |
rev | line source |
---|---|
13290 | 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 | |
13302 | 18 which contain specially tagged comment lines from the code including |
13290 | 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 | |
22202 | 40 are set by something external, e.g. user parameters, file information etc) |
13290 | 41 |
42 - #define, typedefs, structs | |
43 * all global definitions | |
22202 | 44 * all local definitions whose use is not immediately clear by their name |
13302 | 45 (as a rule of thumb, it's better to document too much than not enough) |
13290 | 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 | |
14899
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
90 Doxygen comments should come before the definition: |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
91 |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
92 /** description */ |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
93 int a_variable; |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
94 |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
95 However, you can use '<' to describe things AFTER they are defined, like this: |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
96 |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
97 int some_var; ///< description |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
98 #define foo(x) (x + 2) /**< returns x plus 2 */ |
335964188675
better explain where and how to use doxygen comments
diego
parents:
13302
diff
changeset
|
99 |
13290 | 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> | |
22202 | 127 Set an invisible anchor which can be used to create a link with \ref. |
13290 | 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. |