]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/tech/tn0003.txt
remove ancient SetModal(), it was deprecated long ago and is not present in wxMSW...
[wxWidgets.git] / docs / tech / tn0003.txt
... / ...
CommitLineData
1 Adding wxWidgets class documentation
2 ====================================
3
4This note is aimed at people wishing to add documentation for a
5class to either the main wxWidgets manual, or to their own
6manual.
7
8wxWidgets uses Doxygen to process header input files with embedded
9documentation in the form of C++ comments and output in HTML, and XML
10(Doxygen itself can also output Latex, manpages, RTF, PDF etc).
11See http://www.doxygen.org for more info about Doxygen.
12
13If you want to add documentation of a new class/function to the
14existing manual in docs/doxygen, you need to create a new .h file,
15e.g. myclass.h, under the interface folder, which contains the public
16interface of the new class/function in C++ syntax.
17The documentation can then be added in form of Doxygen comments to
18the header file.
19
20You may also want to write a separate topic file,
21e.g. docs/doxygen/overviews/myclass.h, and add the entry to
22docs/doxygen/mainpages/topics.h.
23
24If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h
25files.
26
27You can generate a first raw version of myclass.h simply taking its
28"real" header and removing all the private and protected sections and
29in general removing everything the user "shouldn't know": i.e. all things
30which are implementation details.
31
32
33Running Doxygen
34===============
35
36First, make sure you have a recent version of Doxygen installed in your system
37(you'll need Doxygen >= 1.5.7).
38
39On Unix:
40
41 1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]
42
43On Windows:
44 1) cd wxWidgets/docs/doxygen
45 2) run regen.bat [format-to-generate]
46
47If you don't specify which format to [re]generate, all output formats will
48be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex",
49"xml" and "all".
50
51The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.
52
53
54Important Dos and Don'ts
55========================
56
57DO:
58
59- Doxygen supports both commands in the form \command and @command;
60 all wxWidgets documentation uses the @command form.
61 Follow strictly this rule.
62
63- strive to use dedicated Doxygen commands for e.g. notes, lists,
64 sections, etc. The "Special commands" page:
65 http://www.stack.nl/~dimitri/doxygen/commands.html
66 is your friend!
67 It's also very important to make a consistent use of the ALIASES
68 defined by wxWidgets' Doxyfile. Open that file for more info.
69
70- when you write true, false and NULL with their C++ semantic meaning,
71 then use the @true, @false and @NULL commands.
72
73- separate different paragraphs with an empty comment line.
74 This is important otherwise Doxygen puts everything in the same
75 paragraph making the result less readable.
76
77- leave a blank comment line between a @section, @subsection, @page
78 and the next paragraph.
79
80- test your changes, both reading the generated HTML docs and by looking
81 at the "doxygen.log" file produced (which will warn you about any
82 eventual mistake found in the comments).
83
84- quote all the following characters prefixing them with a "@" char:
85
86 @ $ \ & < > # %
87
88 unless they appear inside a @code or @verbatim section
89 (you can also use HTML-style escaping, e.g. &amp; rather than @ escaping)
90
91- when using a Doxygen alias like @itemdef{}, you need to escape the
92 comma characters which appear on the first argument, otherwise Doxygen
93 will interpret them as the marker of the end of the first argument and
94 the beginning of the second argument's text.
95
96 E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to
97 write:
98 @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
99
100 Also note that you need to escape only the commas of the first argument's
101 text; second argument can have up to 10 commas unescaped (see the Doxyfile
102 for the trick used to implement this).
103
104- for linking use one of:
105 => the @ref command to refer to topic overviews;
106 => the () suffix to refer to function members of the same class you're
107 documenting or to refer to global functions or macros;
108 => the classname:: operator to refer to functions of classes different
109 from the one you're documenting;
110 => the :: prefix to refer to global variables (e.g. ::wxEmptyString).
111 Class names are auto-linked by Doxygen without the need of any explicit
112 command.
113
114DON'T:
115
116- use jargon, such as 'gonna', or omit the definite article.
117 The manual is intended to be a fluent, English document and
118 not a collection of rough notes.
119
120- use non-alphanumeric characters in link anchors.
121
122- use Doxygen @b @c @e commands when referring to more than a single word;
123 in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
124 HTML-style tags instead
125
126- use HTML style tags for creation of tables or lists.
127 Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
128 @beginDefList, @itemdef, @endDefList, etc.
129 See the Doxyfile.inc for more info.
130
131
132Documentation comment for a class
133=================================
134
135Start off with:
136
137/**
138 @class wxMyClass
139
140 ...here goes the description...
141
142 @beginEventTable
143 @event{EVT_SOME_EVENT(id, func)}:
144 Description for EVT_SOME_EVENT.
145 @endEventTable
146
147 @beginStyleTable
148 @style{wxSOME_STYLE}:
149 Description for wxSOME_STYLE.
150 ...
151 @endStyleTable
152
153 @beginExtraStyleTable
154 @style{wxSOME_EXTRA_STYLE}:
155 Description for wxSOME_EXTRA_STYLE.
156 ...
157 @endExtraStyleTable
158
159 @library{wxbase}
160 @category{cat_shortcut}
161
162 @nativeimpl{wxgtk, wxmsw, ...}
163 @onlyfor{wxgtk, wxmsw, ...}
164
165 @appearance{button.png}
166
167 @stdobjects
168 ...here goes the list of predefined instances...
169
170 @see ...here goes the see-also list...
171 you can make references to topic overviews or other
172 manual pages using the @ref command
173*/
174
175Note that everything *except* the @class, @library and @category
176commands are optionals.
177
178Also note that if you use @section and @subsection in the class description
179(at the beginning), you should use as the section's anchor name "xxxx_yyyy"
180where "xxxx" is the class name without the initial "wx" in lowercase
181and "yyyy" is a lowercase word which uniquely identifies that section.
182E.g.:
183
184/**
185 @class wxMyClass
186
187 This class does not exist really and is only used as an example
188 of best documentation practices.
189
190 @section myclass_special Special functions of this class
191
192 This section describes the functions whose usage is reserved for
193 wxWidgets internal mechanisms... etc etc...
194
195
196 @section myclass_custom Customizing wxMyClass
197
198 What if you want to customize this powerful class?
199 First you should do this and that, etc etc...
200
201
202 @library{wxbase}
203 @category{misc}
204
205 @see wxMyOtherClass
206*/
207
208
209
210Documentation comment for a function
211====================================
212
213Start off with:
214
215/**
216 ...here goes the description of the function....
217
218 @param param1
219 ...here goes the description for the first parameter of this function
220 @param param2
221 ...here goes the description for the second parameter of this function
222 ...
223
224 @return
225 ...here goes the description of what the function returns...
226
227 @note ...here go any eventual notes about this function...
228
229 @remarks ...here go any eventual remarks about this function...
230
231 @see ...here goes the see-also list...
232 */
233
234Note that the @return, @note, @remarks, @see commands are optional.
235
236The @param command has an optional attribute specifying the direction of
237the attribute. Possible values are "in" and "out". E.g.
238
239/**
240 * Copies bytes from a source memory area to a destination memory area,
241 * where both areas may not overlap.
242 * @param[out] dest The memory area to copy to.
243 * @param[in] src The memory area to copy from.
244 * @param[in] n The number of bytes to copy.
245 * @param[in,out] pmisc Used both as input and as output.
246 */
247void func(void *dest, const void *src, size_t n, void *pmisc);
248
249
250Documentation comment for a topic overview
251==========================================
252
253Topic overviews are stored inside the docs/doxygen/overviews folder
254and are completely placed inside a single comment block in the form of:
255
256/*!
257
258 @page overview_tname wxSomeStuff overview
259
260 This page provides an overview of the wxSomeStuff and related classes.
261 ....
262
263 @li @ref overview_tname_intro
264 @li @ref overview_tname_details
265 ...
266
267 <hr>
268
269
270 @section overview_tname_intro Introduction
271
272 ...here goes the introduction to this topic...
273
274
275 @section overview_tname_details Details
276
277 ...here go the details to this topic...
278
279*/
280
281Note that there is a convention in the anchor link names.
282Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
283there is a corresponding link anchor.
284
285The following conventions are used in wxWidgets doxygen comments:
286
2871) all "main" pages of the manual (those which are placed in
288 docs/doxygen/mainpages) have link anchors which begin with "page_"
289
2902) all topic overviews (those which are placed in docs/doxygen/overviews) have
291 link anchors which begin with "overview_"
292
2933) all @section, @subsection, @subsubsection tags should have as link anchor
294 name the name of the parent section plus a specific word separated with an
295 underscore; e.g.:
296
297/*!
298
299 @page overview_tname wxSomeStuff overview
300
301 @section overview_tname_intro Introduction
302 @subsection overview_tname_intro_firstpart First part
303 @subsection overview_tname_intro_secondpart Second part
304 @subsubsection overview_tname_intro_secondpart_sub Second part subsection
305 @subsection overview_tname_intro_thirdpart Third part
306
307 @section overview_tname_details Details
308 ...
309
310*/
311
312
313=== EOF ===
314
315Author: FM (along the lines of the previous technote about tex2rtf)
316Version: $Id$