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