| blob | 0e64c0404d149bf30273b40d2dca821c4c4a22e3 |
1 /*
2 * Copyright 2007 Niels Sascha Reedijk. All rights reserved.
3 * Copyright 2008-2013 Haiku, Inc. All rights reserved.
4 * Distributed under the terms of the MIT License.
5 *
6 * Authors:
7 * Niels Sascha Reedijk, niels.reedijk@gmail.com
8 * John Scipione, jscipione@gmail.com
9 *
10 * Proofreaders:
11 * Alan Smale, ajsmale@gmail.com
12 */
15 /*!
16 \page apidoc Documenting the API
18 This article explains how to document the API. Its intended audience are the
19 Haiku developers who want to document their own classes, and also the
20 members of the API Documentation team who want to brush up the
21 documentation. The guidelines are synchronous with the Haiku Coding
22 Guidelines, which means that the formal requirements are the same where
23 applicable. If you find an inconsistency, it's usually a good idea to
24 report this on the documentation team's mailing list.
26 This document is divided into three sections. \ref formalrequirements
27 describes the demands that are made from the markup and spacing of the
28 files. \ref commands describes the subset of Doxygen commands the Haiku API
29 documentation uses, and which commands are used in which situation. \ref
30 style describes the required style and structure of the documentation. If
31 you are a developer and you want to prepare the first version of the
32 documentation for the API documentation team to go over, have a good look at
33 the formal requirements and the Doxygen commands. In addition, have a quick
34 glance at how to write member and class documentation, since you'll need to
35 know which information is mandatory for the documentation. Aspiring members
36 or members of the API documentation team should read the third section
37 carefully, and should also check out some of the finished documentation to
38 get a good grip on the actual tone, style and contents of the documentation.
40 \section formalrequirements Formal Requirements
42 This section describes formal requirements, such as location and naming of
43 the files, the header blocks of files, what blocks of documentation look
44 like and how to put delimiters to separate different 'blocks' in your source
45 file.
47 \subsection formalrequirements_location Location of the Documentation Source
49 Doxygen, the tool that we use to generate the marked up documentation, has
50 an ingenious parser that is able to scan through both header and source
51 files making it possible to document the API directly in the headers or the
52 source. However, the Haiku project have decided not to put the documentation
53 in either location, and opt for the third option Doxygen provides: to put
54 the documentation into separate files.
56 \note The reasons to not put the documentation in the header files are twofold.
57 First of all, it would add unnecessary cruft to the headers that the
58 compiler will needlessly have to parse, and developers will have a hard
59 time to find the info they are looking for. The second reason is that
60 the system headers are included throughout the tree. It's a waste of
61 electricity to have everybody recompile the entire tree if someone fixes
62 a typo in the documentation. Likewise, the reason to not put the
63 documentation in the source code is that it unnecessarily clutters up
64 that file. By not using direct documentation we lose some advantages,
65 like the fact that developers might be inclined to update the
66 documentation quicker if they change a method, but as you will see we'll
67 have some methods in place to prevent that to a certain extent.
68 There are a few aspects to the naming and locations of files:
69 -# Most important, documentation files \b mirror header files. This
70 not only means that they get the same name, but also that the order
71 of the methods, variables, functions, etc. will have to be the same.
72 -# The root directory of the public API headers is at \c
73 headers/os. In a similar vein, the root of the documentation
74 files is at \c docs/user. The subdirectory
75 structure, or the division of kits, will also be replicated.
76 -# The name of the files is the same as the base of the header files,
77 with the \c dox extension. So \c Something.h becomes \c
78 Something.dox. Note the case!
80 \subsection formalrequirements_headerblock The Header Block
82 Every documentation file will begin with the header block. It's basically a
83 copyright block, with a reference to the author(s) and against which
84 revision the documentation was written.
86 \verbatim
87 /*
88 * Copyright 2007-2013 Haiku, Inc. All rights reserved.
89 * Distributed under the terms of the MIT License.
90 *
91 * Authors:
92 * Niels Sascha Reedijk, niels.reedijk@gmail.com
93 *
94 * Proofreaders:
95 * Alan Smale, ajsmale@gmail.com
96 *
97 * Corresponds to:
98 * headers/os/support/String.h rev 19731
99 * src/kits/support/String.cpp rev 19731
100 */
101 \endverbatim
103 The example above has a few elements that you should take note of:
104 -# The header is put in a standard C comment, which is enclosed between
105 \verbatim
106 /*
107 \endverbatim
108 and
109 \verbatim
110 */
111 \endverbatim
112 -# Every line starts with a whitespace and an asterisk followed by another
113 space. If the text is part of a category, such as <tt>Authors</tt>, put
114 three spaces after the delimiter.
115 -# The first line is empty, then we get to the copyright notice. You may
116 either retain the copyright yourself, or you can attribute to to Haiku
117 Inc. It's your choice. The next line is the \e MIT License notice,
118 followed by an empty line.
119 -# Then there is a label <tt>Authors:</tt>, which is followed by
120 lines with names and email addresses. The latter one is optional, but
121 recommended. Each author is proceeded by two tabs after the asterisk.
122 -# In the same vein there is the label <tt>Proofreaders:</tt> in case the
123 file has been proofread.
124 -# The final part is underneath the label <tt>Corresponds to:</tt>.
125 Underneath there is a list of files and their svn revisions that the
126 current documentation is known to correspond with.
127 -# The header block ends with the
128 \verbatim
129 */
130 \endverbatim
131 where the asterisk is aligned with the ones above it.
133 \subsection formalrequirements_blocks Blocks
135 Blocks are the basic units of documentation for Doxygen. At first it will
136 feel like overkill to use blocks, but realize that Doxygen was initially
137 designed to operate on header and source files, and then the blocks of
138 documentation would be before the definition or declaration of the methods,
139 functions, etcetera. Doxygen is used to operating on blocks, and that's why
140 we need to reproduce them in our \c dox files.
142 Blocks should adhere to the following standards:
143 -# All blocks open with
144 \verbatim
145 /*!
146 \endverbatim
147 and close with
148 \verbatim
149 */
150 \endverbatim
151 -# The documentation is placed in between these markers.
152 -# All the contents in between the markers is indented by tabs. The tab
153 length should be four.
154 -# Between blocks, there should be two empty lines.
155 -# The maximum width of the contents between blocks is 80 columns. <b>Try
156 not to cross this limit</b>, because it will severely limit
157 readability.
159 Example:
160 \verbatim
161 /*!
162 \fn bool BList::AddItem(void *item)
163 \brief Append an item to the list.
165 \param item The item to add.
166 \retval true The item was appended.
167 \retval false Item was not appended, since resizing the list failed.
168 \sa AddItem(void *item, int32 index)
169 */
170 \endverbatim
172 \note Doxygen also allows the use of single line comments, starting with
173 \c //!, however, we won't use these \b except for group markers, which
174 you can read more about in the next section.
176 \subsection formalrequirements_delimiters Delimiters
178 Many of the header files in the Haiku API just document one class or one
179 group of functions. However, there be a time when you come across a more
180 complex header and for the sake of clarity in your \c dox file you want to
181 mark the sections. Use the standard delimiter marker for this, which
182 consists of five slashes, a space, the title of the section, a space and
183 another five slashes. Like this: <tt>///// Global Functions /////</tt>.
185 \note This is only for the source files and for you as documenter. It will
186 not show up in the actual generated documentation!
188 \section commands Doxygen Commands
190 This section describes all the Doxygen commands that will be used in the
191 Haiku API documentation. As a rule, Doxygen commands start with a backslash
192 (\\) and are followed by whitespace (such as a space or a newline), with the
193 exception of group markers; this is discussed in more detail later on. The
194 commands can be divided into several categories, which are described in the
195 following subsections.
197 \note This section does not discuss which commands you should actually use
198 in documentation. See the next section on \ref style for that. This
199 section merely explains the different groupings and syntaxes of
200 commands.
202 Most commands accept an argument. Arguments can be one of these three types:
203 - \<single_word\> - The argument is a single word.
204 - (until the end of the line) - The argument runs until the end of the line.
205 - {paragraph} - The argument runs for an entire paragraph. A paragraph is
206 ended by an empty line, or if another command that defines a \ref
207 commands_sections sections is found. Note that if you use commands that
208 work on a paragraph and you split it over multiple lines (because of the
209 maximum line width of 80 characters or because it looks better), you
210 will have to indent subsequent lines that belong to the paragraph with
211 two more spaces, making the total of four. This is to visually
212 distinguish paragraphs for other documenters.
214 \subsection commands_definitions Block Definitions
216 Because our API documentation is not done in the source, nor in the headers,
217 Doxygen needs to be helped with figuring out what the documentation in the
218 different blocks actually are about. That's why the first line in a
219 documentation block would be one of the following commands:
221 - \c \\class \<name\> \n
222 Tells Doxygen that the following section is going to be on the class as
223 specified by \a name.
224 - \c \\fn (function declaration) \n
225 This block is going to be about the function that corresponds to the
226 given declaration. Please note that the declaration is what you find in
227 the source file, so if class members are declared, the classname and the
228 scope operator, \c ::, are to be added as well. Modifiers such as \c
229 const should be included.
230 - \c \\var (variable declaration) \n
231 This block is going to be about the variable indicated by the
232 declaration. This means basically that data members of a class should
233 have the classname and the scope operator as well.
234 - \c \\typedef (typedef declaration) \n
235 This block is going to be about the typedef indicated by the
236 declaration. Copy the declaration exactly, including the leading \c
237 typedef keyword.
238 - \c \\struct \<name\> \n
239 Tells Doxygen the section is going to be on the \c struct indicated by
240 \a name.
241 - \c \\def \<name\> \n
242 This block is going to be about the \c \#define with the identifier \a
243 name.
244 - \c \\page \n
245 This block represents a page. See the section on \ref commands_pages for
246 detailed information on pages.
248 \subsection commands_sections Sections in Member Documentation
250 If you have a look at the output that Doxygen generates, you can see that
251 there are recurring sections in the documentation. Documentation that
252 belongs to a certain section should be placed after a command that marks the
253 start of that section. All the commands take a paragraph as answer. A
254 paragraph ends with a whitespace, or with a command that marks a new
255 section. Note that this list only shows the syntax of the commands. For the
256 semantics, have a look at the next section on style. In member documentation
257 you can use the following:
259 - \c \\brief {brief description} \n
260 This is the only \b mandatory section. Every member should have at least
261 a brief description.
262 - \c \\param \<parameter-name\> {parameter description} \n
263 This section describes a parameter with the name \a parameter-name. The
264 parameter name must match the function declaration, since Doxygen will
265 check if all the documented parameters exist.
266 - \c \\return {description of the return value} \n
267 This section describes the return value. This is a totally free form
268 paragraph, whereas \c \\retval has a more structured form.
269 - \c \\retval \<value\> {description} \n
270 This section describes the return value indicated by \a value.
271 - \c \\see {references} \n
272 This section contains references to other parts of the documentation.
274 There are also a number of things that can be used in pages and member
275 documentation. See the style section to find out the appropriate situations
276 in which to use them.
277 - \c \\note {text}
278 - \c \\attention {text}
279 - \c \\warning {text}
280 - \c \\remarks {text}
282 \subsection commands_markup Markup
284 Sometimes you might require certain text to have a special markup, to make
285 words stand out, but also if you want to have example code within the
286 documentation you'll need a special markup. Doxygen defines three types of
287 commands. There are commands that work on single words, commands that work
288 on longer phrases and commands that define blocks. Basically, the single
289 letter commands are commands that work on a the next word. If you need to
290 mark multiple words or sentences, use the HTML-style commands. Finally, for
291 blocks of code or blocks of text that need to be in "typewriter" font, use
292 the block commands. Have a look at the following listing:
294 - \c \\a \n
295 Use to refer to parameters or arguments in a running text, for example
296 when referring to parameters in method descriptions.
297 - <b>Bold text</b>
298 - For single words, use \c \\b.
299 - For multiple words, enclose between the \c \<b\> and \c \<\\b\> tags.
300 - <tt>Typewriter font</tt> \n
301 This can be used to refer to constants, or anything that needs to be in
302 a monospace, or typewriter, font. There are a few options
303 - \c \\c for single words.
304 - \c \<tt\> and \c \<\\tt\> for multiple words or phrases
305 - The commands \c \\verbatim and \c \\endverbatim. Everything between
306 these two commands will be put in a distinct block that stands out
307 from the rest of the text.
308 - The commands \c \\code and \c \\endcode do the same, but Doxygen will
309 parse the contents and try to mark up the code to make it look a
310 little bit nicer.
311 - <em>Emphasis</em>
312 - \c \\e for single words.
313 - \c \<em\> and \c \<\\em\> for phrases.
315 \subsection commands_pages Page Commands
317 Pages are a very special element of the documentation. They are not
318 associated with any kind of module, such as files or classes, and therefore,
319 since they're not members, some of the structuring commands won't work.
320 Important to know is that a page is the complete length of the block, so
321 dividing it up in subsections by starting new blocks will not work. Instead,
322 Doxygen provides some commands to structure text on a page.
324 First of all, you define a new page by using the \c \\page command. This
325 command takes two arguments: a \c \<name\> and <tt>(a title)</tt>. The name
326 is the internal identifier that can be used in linking between pages (see
327 \ref commands_miscellaneous for \c \\ref). After you've defined the block
328 to be a page, you can start writing the contents.
330 For more complicated pages, you might want to divide the page up in
331 sections. Use the \c \\section command to define a new section. It takes the
332 same arguments as \c \\page, namely the \c \<name\> and the
333 <tt>(title)</tt>. If you need a deeper hierarchy you may use \c \\subsection
334 and \c \\subsubsection, again, both with the same syntax. If you need to
335 distinguish between sections in sub-sub-sections, you are able to use
336 \c \\paragraph, which takes the same arguments.
338 \note Before and after each of the commands above, you need to have an empty
339 line so as to provide readability. It is not necessary to indent
340 sections and subsections more than the normal two spaces, as long as you
341 keep the section markers clear.
343 \warning If you are entering the realm of subsections and sub-subsections,
344 think about the nature of your page. Either it needs to be split up into
345 multiple pages, or what you're writing is too complex and would be
346 better off as a big tutorial on the Haiku website.
348 If you are creating multiple pages that are related, you will be able to
349 structure them in a tree by using the \c \\subpage command. This will rank
350 the different pages in a tree structure. It will put a link in the place of
351 the command, so you should place it at the top of the parent place and use
352 it as an index.
354 \subsection commands_grouping Member Grouping Commands
356 Doxygen makes it possible to group certain members together. It is used
357 in the BString class for example, where the members are grouped by what kind
358 of operation they perform, such as appending, finding, etc. Defining groups
359 is currently not as powerful as it could be, but if you use it inside
360 classes, you will be fine if you follow the instructions presented in
361 this section.
363 \note If you are looking on how to add classes to kits, see
364 \ref commands_miscellaneous and have a look at the \c \\ingroup command.
366 Groups of members are preceded by a block that describes what the group is
367 about. You are required to give each group of members at least a name. Have
368 a look at the example:
370 \verbatim
371 /*!
372 \name Appending Methods
374 These methods append things to the object.
375 */
378 //! \@{
381 ... methods ...
384 //! \@}
386 \endverbatim
388 The block preceding the block opening marker, <tt>//! \@{</tt>, contains a
389 \c \\name command and a paragraph that gives a description. The header
390 block can be as long or short as you want, but please don't make it too
391 long. See the \ref style section on how to effectively write group headers.
392 The members that you want to belong to the group are between the group
393 opening and closing markers.
395 \note Group headers don't have a \c \\brief description.
397 \subsection commands_miscellaneous Miscellaneous Commands
399 There are some commands that don't fit into the categories above, but that
400 you will end up using every now and then. This section will describe those
401 commands.
403 The first one is \c \\n. This commands sort of belongs to the category of
404 markup commands. It basically forces a newline. Because Doxygen parses
405 paragraphs as a single contiguous entity, it's not possible to mark up the
406 text using carriage returns in the documentation. \c \\n forces a newline in
407 the output. So in HTML it will be translated into a \c \<br\\\>.
409 Sometimes there are some parts of the API that you don't want to be visible.
410 Since Doxygen extracts all the public and protected members from a class,
411 and virtually every member from a file, you might want to force it to hide
412 certain things. If so, use the \c \\internal command. If you place this just
413 after the block marker, the command will be hidden from documentation. Any
414 further documentation or remarks you put inside the block will not be
415 visible in the final documentation.
417 Images can be a valuable addition to documentation. To include ones you
418 made, use the \c \\image command. It has the following prototype:
419 <tt>\\image \<format\> \<file\></tt>. The format is currently fixed at
420 \c html. The file refers to the filename relative to the location of the
421 documentation file. Any images you want to add should be in the same
422 location as the dox file, so only the file name will suffice.
424 Modules are defined in the main book, and you can add classes to them by
425 using the \c \\ingroup command. This commands adds the class to the module
426 and groups it on a separate page. At this moment, the group handling has yet
427 to be finalized. For now, add the classes to the kit they belong in. In the
428 future this might change.
430 Finally, it is a good idea to link between parts of the documentation. There
431 are two commands for that. The first one is \c \\ref, which enable you to
432 refer to pages, sections, etc. that you created yourself. The second one is
433 \c \\link which refers to members. The first one is takes one word as an
434 argument, the name of the section, and it inserts a link with the name of
435 the title. \c \\link is more complex. It should always be accompanied by \c
436 \\endlink. The first word between the two commands is the object that is
437 referred to, and the rest is the link text.
439 \section style Writing Guidelines
441 This final section will present guidelines for the actual writing of the
442 documentation. Both the structure of the documentation, which sections to
443 use when, and the style of the writing will be discussed. Before diverging
444 into the requirements for file and class descriptions, member descriptions
445 and pages, there are some general remarks that apply to all types of
446 documentation.
448 First of all, everything you write should be in <em>proper English
449 sentences</em>. Spelling, grammar, punctuation, make sure you adhere to the
450 standards. It also means the following:
451 - It means that every sentence should at least have a
452 subject and a verb (unless it's an imperative statement).
453 - Also use the proper terminology. Remember, you are dealing with C++
454 here, which means you should use the right names. So use \b method
455 instead of function, and data member instead of variable (where
456 appropriate).
457 - Avoid in-formalism. Avoid constructs like 'if you want to
458 disconnect the object', but rather use 'to disconnect the object'. Avoid
459 familiarizes, or jokes.
461 \remarks It isn't the goal to create dry, legal-style documentation. Just
462 try to find a balance. Read through documentation that's already been
463 approved to get a hint of what you should be aiming for.
464 \remarks If you are having a problem with phrasing certain things, put it
465 down in such a way that it says everything it needs to. A proofreader
466 might then be able to rephrase it to a better style.
468 Throughout the documentation you might want to provide hints, warnings or
469 remarks that might interrupt the flow of the text, or that need to visually
470 stand out from the rest. Doxygen provides commands for paragraphs that
471 display remarks, warnings, notes and points of attention. You can use these
472 commands in case you meet one or more of the following requirements:
473 - The point is for a specific audience, such as beginners in the Haiku API.
474 Notes on what to read first, or mistakes that may be made by beginners
475 will not be for the entire audience, and such should be separated. These
476 kinds of notes should be at the end of blocks.
477 - The point needs to visually stand out. This is especially the case with
478 remarks, but could also apply for other types.
479 - The point is not completely relevant to the text and therefore should be
480 separated so that it doesn't interrupt the main flow.
482 This listing shows which one to use for which situation:
483 - \c \\attention
484 - Used when the developer is bound to make a mistake, when the API is
485 ambiguous. The difference between this and a warning is that
486 warnings warn about things that are the developers fault, and
487 attention blocks warn about things that might go wrong
488 because of the way the API is structured.
489 - Used to warn for abuse of the API that might be caused by the way the
490 internals of the system are structured.
491 - \c \\warning
492 - Used to warn developers about using the API in a certain way. Warnings
493 apply especially to new developers that aren't completely familiar
494 with the API and that might want to abuse it. For example, the
495 thread safety of BString requires a warning.
496 - \c \\note
497 - Used to place references to other documentation that might not be
498 directly related to the text. For example, BLooper will have a
499 direct reference to BHandler in the class description, but
500 BMessenger will be mentioned in a note because it does not directly
501 influence the use of the class.
502 - Can also be used for useful hints or notes that somehow need to stand
503 out from the rest of the text.
504 - \c \\remarks
505 - Remarks are small notes that would interrupt the flow of the text. For
506 example, if you in a text ignore a certain condition that is so
507 extremely rare and uncommon, you can put a remark at the end of the
508 text to tell that you have been lying.
509 - Remarks interact with the text whereas notes add something unmentioned
510 to it.
512 \subsection style_files File Descriptions
514 The design of Doxygen makes it very file oriented, and this might come off
515 as inconvenient. At the moment, how to actually group the documentation is
516 still under debate, but it does not change the requirement that a header
517 needs to be documented before the members of that header can be documented.
518 As such, the first documentation block in your \c dox file will be the block
519 that describes the header. Examples:
521 \verbatim
522 /*!
523 \file String.h
524 \brief Defines the BString class and global operators and functions for
525 handling strings.
526 */
529 /*!
530 \file SupportDefs.h
531 \brief Defines basic types and definitions for the Haiku API.
532 */
533 \endverbatim
535 The first statement defines what the block is about, namely the header file.
536 The second element is the \c \\brief remark on what it contains. The first
537 file defines the BString class and some global operators. You can see that
538 reflected in the description. SupportDefs.h does not define classes, but
539 rather a range of different functions and defines, so the text refers to
540 that.
542 \remarks \\brief documentation for files is about what it \e implements, as
543 header files are passive (whereas members and functions are active).
544 Thus, use the third person form of the verb.
546 \subsection style_classes Class Descriptions
548 Classes are the basic building blocks in the Haiku API and as such have
549 extensive documentation. This section will go over the actual class
550 description. This section will present a list of items you should think
551 about when writing the class description. This doesn't mean you'll have
552 to include every item, it merely serves as a guiding principle that helps
553 organise your thoughts. Have a look at the list:
555 -# The \c \\brief description is \b obligatory. This description describes
556 what it is. For example, BDataIO: "Abstract interface for objects that
557 provide read and write access to data." Note that this description is
558 not a full sentence, but it does end with a period.
559 -# One or more paragraphs that give a broad overview of what the class can
560 do. Describe things like what it works on, when you want to use it, what
561 advantage it might give over other directly related alternatives. Also
562 describe if a class is made to be derived from, and if so, how. Make
563 sure that a developer in the first few paragraphs can judge if what he
564 wants to do can be done with this class.
565 -# One or more paragraphs that show how this class ties in with the rest
566 of the kit or the API. What objects does it work with, how it interacts
567 with the servers, etcetera.
568 -# One or more paragraphs that give a concrete example or use case. Keep it
569 tidy and self contained. If you use code examples, make sure your
570 examples adhere to Haiku's coding guidelines. Remember, an example can
571 illustrate better than a few paragraphs of text.
572 -# End with a list of references to other classes, functions, pages, etc.
573 that might be of interest to the reader.
575 When documenting classes, don't be to exhaustive. Avoid becoming a tutorial
576 or a complete guide. This documentation is for reference only. If you want
577 to enlighten the reader on bigger subjects, consider writing a separate
578 documentation page that connects the different points you want to make.
580 Also, you don't have to put in any groupings of members in class
581 descriptions. If you want to do that, physically divide the members up in
582 groups. Look at the \ref commands_grouping for the actual commands, and at
583 \ref style_groups for help on writing group headers.
585 \subsection style_members Members and Functions
587 Members and functions share the same basic Doxygen syntax, and they can be
588 documented in a similar way. That's why this section deals with them
589 together. Documenting members is probably the main thing you'll do when
590 writing the actual documentation. There are some guidelines as to how, but
591 the actual implementation probably differs per class. Keep the following
592 points in mind:
594 -# To repeat a very important fact, the first line is a \c \\fn line. This
595 line needs to match the declaration, which is in the source file. This
596 means that for members, also the class name and the scope indicator (::)
597 should be present. Also note that this line doesn't have to adhere to
598 the 80 column width limit.
599 -# The first command is always the \c \\brief command. Give a short and
600 clear description. The description starts with a capital letter and ends
601 with a dot. Don't write the description saying what the method does,
602 like "Starts the timer", but rather as what it will do: "Start the
603 timer." -# If the brief description doesn't cover all of what the method
604 or function does, then you can add a few paragraphs that explain it in
605 more depth. Don't be too verbose, and use an example to illustrate
606 points. Point out any potential misunderstandings or problems you expect
607 developers to have, but don't repeat the class documentation too much.
608 -# You are obliged to then document all the parameters. Use the \c \\param
609 command for that. For the description, use a short phrase such as "The
610 offset (zero based) where to begin the move." Note the capital and the
611 dot.
612 -# If the function is non-void, then you'll have to specify what it will
613 return. In case of fixed values, have a look at \c \\retval. You'll use
614 this one when the return type is a bool or a status_t. In case of
615 something else, use \c \\return. You can also combine these two. For
616 example, a method that returns a length (positive) or an error code
617 (negative).
618 -# Use \c \\see if you have any references to other methods, classes or
619 global functions. At least document all the overloaded methods. Also add
620 methods that do the opposite of this method, or methods that are
621 intimately related.
623 In case of overloaded members, you'll need to make a decision. If you need
624 to copy too much information, you might resort to putting it in one
625 paragraph with the text "This is an overloaded member function, and differs
626 from \<name\> only by the type of parameter it takes." That will keep the
627 copying down and will point developers right to the place where they can get
628 more documentation.
630 Again, like class descriptions, you'll have to find a good middle-ground
631 between too much information, and too little. Again, write for the broadest
632 audience possible, and resort to notes and warnings for specialised
633 audiences.
635 \subsection style_variables Enumerations, Variables and Defines
637 This section helps you document (member) variables and defines that define
638 constants, as well as enumerations and their values. If you need to document
639 a \c \#define macro that takes arguments, have a look at \ref style_members
641 The \c \\brief description of all these types follow a similar structure.
642 They are a short phrase that mention what the variable contains. Example:
644 \verbatim
645 /*!
646 \var char* BString::fPrivateData
647 \brief BString's storage for data.
649 This member is deprecated and might even become \c private in future
650 releases.
652 If you are planning to derive from this object and you want to manipulate
653 the raw string data, please have a look at LockBuffer() and UnlockBuffer().
654 */
655 \endverbatim
657 The variables you are going to encounter are either \c public or
658 \c protected member variables, or global variables that have a certain
659 significance. In the case of member variables, you'll need to document what
660 they mean and how the developer should manipulate them. If the class is one
661 that is meant to be derived from, make sure that in the description of the
662 variable you mention how it interacts with the others, and how the developer
663 should make sure that the internal coherence of the data and code members of
664 the inherited class is maintained.
666 Global variables will mostly be constants. If so, document what they stand
667 for and what they might be used for, as well as which classes and functions
668 depend on that constant. If the variable is meant to be changed by the
669 developer, explain what values are valid and which functions and classes
670 depend on this variable.
672 Defines are usually used as message constants. Give a short description of
673 what the message constant stands for, and where it might be send from and
674 where it might be received.
676 Enumerations can either be anonymous or named. In case of the latter, you
677 can give a description of the enumeration in a documentation block that
678 starts with an \c \\enum command, followed by the name of the enumeration.
679 If the enumeration is within the scope of a class, prepend the classname and
680 the scope indicator. In case of an anonymous enum, you can only document the
681 individual members (which you should do for the named enumerations as well),
682 which can be done within code blocks that start with the \c \\var command.
683 Doxygen will know that it's an enumeration value, don't worry about mixups.
684 If the enumeration value is within a class, prepend the classname and scope
685 indicator. Give a short description of the value, which methods react to
686 it, where it might be used, etcetera. Don't go as far as to copy information
687 too much. For example, if you use an enumeration in only one class and you
688 document the possible values there, then don't do that again for the
689 enumeration documentation: rather just refer to it. That sort of
690 documentation belongs to the class description, not to the enumeration.
692 \subsection style_groups Groups
694 If you subdivide members of classes into groups, you have the ability to
695 apply some general information that will be listed above the listing of the
696 members in that group. See the section \ref commands_grouping on how to
697 define groups. This section is on what to put in the header block.
699 First of all, it's probably a good idea to give your group a name. This name
700 will be printed as a title and will enhance the clarity of what the group
701 contains. If you put the \c \\name command as the first command of a group,
702 the rest of the words on that line will be used as the title. You should
703 choose simple titles of no more than three words.
705 It's possible to add one or two paragraphs of information. These paragraphs
706 should contain some quick notes on which of the members in that group to use
707 for what purpose. See it as a quick subdivision that a developer could use
708 as a guide to see which method he actually wants to use. Don't go on
709 describing the methods in detail though, that's what the member
710 documentation is about. Have a look at the example:
712 \verbatim
713 /*!
714 \name Comparison Methods
716 There are two different comparison methods. First of all there is the whole
717 range of operators that return a boolean value, secondly there are methods
718 that return an integer value, both case sensitive and case insensitive.
720 There are also global comparison operators and global compare functions.
721 You might need these in case you have a sort routine that takes a generic
722 comparison function, such as BList::SortItems().
724 See the String.h documentation file to see the specifics, as they are
725 basically the same as implemented in this class.
726 */
727 \endverbatim
729 Straight, to the point, gives no more information than necessary. Divides
730 the members up into two groups and refers to other functions the developer
731 might be looking for. The hard limit is two (short) paragraphs. Using more
732 will not improve clarity.
733 */