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