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