/** Copyright 2007 Niels Sascha Reedijk. All rights reserved.* Copyright 2008-2013, 2020 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com* John Scipione, jscipione@gmail.com** Proofreaders:* Alan Smale, ajsmale@gmail.com*//*!\page apidoc Documenting the APIThis article explains how to document the API. Its intended audience are theHaiku developers who want to document their own classes, and also themembers of the API Documentation team who want to brush up thedocumentation. The guidelines are synchronous with the Haiku CodingGuidelines, which means that the formal requirements are the same whereapplicable. If you find an inconsistency, it's usually a good idea toreport this on the documentation team's mailing list.This document is divided into three sections. \ref formalrequirementsdescribes the demands that are made from the markup and spacing of thefiles. \ref commands describes the subset of Doxygen commands the Haiku APIdocumentation uses, and which commands are used in which situation. \refstyle describes the required style and structure of the documentation. Ifyou are a developer and you want to prepare the first version of thedocumentation for the API documentation team to go over, have a good look atthe formal requirements and the Doxygen commands. In addition, have a quickglance at how to write member and class documentation, since you'll need toknow which information is mandatory for the documentation. Aspiring membersor members of the API documentation team should read the third sectioncarefully, and should also check out some of the finished documentation toget a good grip on the actual tone, style and contents of the documentation.\section formalrequirements Formal RequirementsThis section describes formal requirements, such as location and naming ofthe files, the header blocks of files, what blocks of documentation looklike and how to put delimiters to separate different 'blocks' in your sourcefile.\subsection formalrequirements_location Location of the Documentation SourceDoxygen, the tool that we use to generate the marked up documentation, hasan ingenious parser that is able to scan through both header and sourcefiles making it possible to document the API directly in the headers or thesource. However, the Haiku project have decided not to put the documentationin either location, and opt for the third option Doxygen provides: to putthe documentation into separate files.\note The reasons to not put the documentation in the header files are twofold.First of all, it would add unnecessary cruft to the headers that thecompiler will needlessly have to parse, and developers will have a hardtime to find the info they are looking for. The second reason is thatthe system headers are included throughout the tree. It's a waste ofelectricity to have everybody recompile the entire tree if someone fixesa typo in the documentation. Likewise, the reason to not put thedocumentation in the source code is that it unnecessarily clutters upthat file. By not using direct documentation we lose some advantages,like the fact that developers might be inclined to update thedocumentation quicker if they change a method, but as you will see we'llhave some methods in place to prevent that to a certain extent.There are a few aspects to the naming and locations of files:-# Most important, documentation files \b mirror header files. Thisnot only means that they get the same name, but also that the orderof the methods, variables, functions, etc. will have to be the same.-# The root directory of the public API headers is at \cheaders/os. In a similar vein, the root of the documentationfiles is at \c docs/user. The subdirectorystructure, or the division of kits, will also be replicated.-# The name of the files is the same as the base of the header files,with the \c dox extension. So \c Something.h becomes \cSomething.dox. Note the case!\subsection formalrequirements_headerblock The Header BlockEvery documentation file will begin with the header block. It's basically acopyright block, with a reference to the author(s) and against whichrevision the documentation was written.\verbatim/** Copyright 2007-2013 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com** Proofreaders:* Alan Smale, ajsmale@gmail.com** Corresponds to:* headers/os/support/String.h rev 19731* src/kits/support/String.cpp rev 19731*/\endverbatimThe example above has a few elements that you should take note of:-# The header is put in a standard C comment, which is enclosed between\verbatim/*\endverbatimand\verbatim*/\endverbatim-# Every line starts with a whitespace and an asterisk followed by anotherspace. If the text is part of a category, such as <tt>Authors</tt>, putthree spaces after the delimiter.-# The first line is empty, then we get to the copyright notice. You mayeither retain the copyright yourself, or you can attribute to to HaikuInc. It's your choice. The next line is the \e MIT License notice,followed by an empty line.-# Then there is a label <tt>Authors:</tt>, which is followed bylines with names and email addresses. The latter one is optional, butrecommended. Each author is proceeded by two tabs after the asterisk.-# In the same vein there is the label <tt>Proofreaders:</tt> in case thefile has been proofread.-# The final part is underneath the label <tt>Corresponds to:</tt>.Underneath there is a list of files and their svn revisions that thecurrent documentation is known to correspond with.-# The header block ends with the\verbatim*/\endverbatimwhere the asterisk is aligned with the ones above it.\subsection formalrequirements_blocks BlocksBlocks are the basic units of documentation for Doxygen. At first it willfeel like overkill to use blocks, but realize that Doxygen was initiallydesigned to operate on header and source files, and then the blocks ofdocumentation would be before the definition or declaration of the methods,functions, etcetera. Doxygen is used to operating on blocks, and that's whywe need to reproduce them in our \c dox files.Blocks should adhere to the following standards:-# All blocks open with\verbatim/*!\endverbatimand close with\verbatim*/\endverbatim-# The documentation is placed in between these markers.-# All the contents in between the markers is indented by tabs. The tablength should be four.-# Between blocks, there should be two empty lines.-# The maximum width of the contents between blocks is 80 columns. <b>Trynot to cross this limit</b>, because it will severely limitreadability.Example:\verbatim/*!\fn bool BList::AddItem(void *item)\brief Append an item to the list.\param item The item to add.\retval true The item was appended.\retval false Item was not appended, since resizing the list failed.\sa AddItem(void *item, int32 index)*/\endverbatim\note Doxygen also allows the use of single line comments, starting with\c //!, however, we won't use these \b except for group markers, whichyou can read more about in the next section.\subsection formalrequirements_delimiters DelimitersMany of the header files in the Haiku API just document one class or onegroup of functions. However, there be a time when you come across a morecomplex header and for the sake of clarity in your \c dox file you want tomark the sections. Use the standard delimiter marker for this, whichconsists of five slashes, a space, the title of the section, a space andanother five slashes. Like this: <tt>///// Global Functions /////</tt>.\note This is only for the source files and for you as documenter. It willnot show up in the actual generated documentation!\subsection formalrequirements_internal Internal documentationIt is possible that there is documentation for parts of the API that arenot (yet) part of the public API. It could either be that the documentationis part of the public header file (usually hidden behind a namespace like\c BPrivate), or it is part of a private header file.In case you are in the situation where you need to store private API docs,you should put the entirety of the documentation in a conditional block,with the \c INTERNAL identifier. You open the block with the command<tt>//! \\cond INTERNAL</tt> and end the block with the command<tt>//! \\endcond INTERNAL</tt>.There are two different cases where you must or could use these blocks:-# For non-public API of a <em>public header file</em>, you must alwaysadd the classes and other elements to the documentation even if theyare placeholders, and put them in the conditional block.-# For parts of the non-public API that is in a <em>private headerfile</em>, you could put the documentation in a conditional block. Ifyou choose to do so, you must document all elements in that headerfile.\section commands Doxygen CommandsThis section describes all the Doxygen commands that will be used in theHaiku API documentation. As a rule, Doxygen commands start with a backslash(\\) and are followed by whitespace (such as a space or a newline), with theexception of group markers; this is discussed in more detail later on. Thecommands can be divided into several categories, which are described in thefollowing subsections.\note This section does not discuss which commands you should actually usein documentation. See the next section on \ref style for that. Thissection merely explains the different groupings and syntaxes ofcommands.Most commands accept an argument. Arguments can be one of these three types:- \<single_word\> - The argument is a single word.- (until the end of the line) - The argument runs until the end of the line.- {paragraph} - The argument runs for an entire paragraph. A paragraph isended by an empty line, or if another command that defines a \linkcommands_sections section \endlink is found. Note that if you usecommands that work on a paragraph and you split it over multiple lines(because of the maximum line width of 80 characters or because it looksbetter), you will have to indent subsequent lines that belong to theparagraph with two more spaces, making the total of four. This is tovisually distinguish paragraphs for other documenters.\subsection commands_definitions Block DefinitionsBecause our API documentation is not done in the source, nor in the headers,Doxygen needs to be helped with figuring out what the documentation in thedifferent blocks actually are about. That's why the first line in adocumentation block would be one of the following commands:- \c \\class \<name\> \nTells Doxygen that the following section is going to be on the class asspecified by \a name.- \c \\fn (function declaration) \nThis block is going to be about the function that corresponds to thegiven declaration. Please note that the declaration is what you find inthe source file, so if class members are declared, the classname and thescope operator, \c ::, are to be added as well. Modifiers such as \cconst should be included.- \c \\var (variable declaration) \nThis block is going to be about the variable indicated by thedeclaration. This means basically that data members of a class shouldhave the classname and the scope operator as well.- \c \\typedef (typedef declaration) \nThis block is going to be about the typedef indicated by thedeclaration. Copy the declaration exactly, including the leading \ctypedef keyword.- \c \\struct \<name\> \nTells Doxygen the section is going to be on the \c struct indicated by\a name.- \c \\def \<name\> \nThis block is going to be about the \c \#define with the identifier \aname.- \c \\page \nThis block represents a page. See the section on \ref commands_pages fordetailed information on pages.\subsection commands_sections Sections in Member DocumentationIf you have a look at the output that Doxygen generates, you can see thatthere are recurring sections in the documentation. Documentation thatbelongs to a certain section should be placed after a command that marks thestart of that section. All the commands take a paragraph as argument. Aparagraph ends with an empty line, or with a command that marks a newsection. Note that this list only shows the syntax of the commands. For thesemantics, have a look at the next section on style. In member documentationyou can use the following:- \c \\brief {brief description} \nThis is the only \b mandatory section. Every member should have at leasta brief description.- \c \\param \<parameter-name\> {parameter description} \nThis section describes a parameter with the name \a parameter-name. Theparameter name must match the function declaration, since Doxygen willcheck if all the documented parameters exist.- \c \\return {description of the return value} \nThis section describes the return value. This is a totally free formparagraph, whereas \c \\retval has a more structured form.- \c \\retval \<value\> {description} \nThis section describes the return value indicated by \a value.- \c \\see {references} \nThis section contains references to other parts of the documentation.There are also a number of things that can be used in pages and memberdocumentation. See the style section to find out the appropriate situationsin which to use them.- \c \\note {text}- \c \\attention {text}- \c \\warning {text}- \c \\remarks {text}\subsection commands_markup MarkupSometimes you might require certain text to have a special markup, to makewords stand out, but also if you want to have example code within thedocumentation you'll need a special markup. Doxygen defines three types ofcommands. There are commands that work on single words, commands that workon longer phrases and commands that define blocks. Basically, the singleletter commands are commands that work on a the next word. If you need tomark multiple words or sentences, use the HTML-style commands. Finally, forblocks of code or blocks of text that need to be in "typewriter" font, usethe block commands. Have a look at the following listing:- \c \\a \nUse to refer to parameters or arguments in a running text, for examplewhen referring to parameters in method descriptions.- <b>Bold text</b>- For single words, use \c \\b.- For multiple words, enclose between the \c \<b\> and \c \<\\b\> tags.- <tt>Typewriter font</tt> \nThis can be used to refer to constants, or anything that needs to be ina monospace, or typewriter, font. There are a few options- \c \\c for single words.- \c \<tt\> and \c \<\\tt\> for multiple words or phrases- The commands \c \\verbatim and \c \\endverbatim. Everything betweenthese two commands will be put in a distinct block that stands outfrom the rest of the text.- The commands \c \\code and \c \\endcode do the same, but Doxygen willparse the contents and try to mark up the code to make it look alittle bit nicer.- <em>Emphasis</em>- \c \\e for single words.- \c \<em\> and \c \<\\em\> for phrases.\subsection commands_pages Page CommandsPages are a very special element of the documentation. They are notassociated with any kind of module, such as files or classes, and therefore,since they're not members, some of the structuring commands won't work.Important to know is that a page is the complete length of the block, sodividing it up in subsections by starting new blocks will not work. Instead,Doxygen provides some commands to structure text on a page.First of all, you define a new page by using the \c \\page command. Thiscommand takes two arguments: a \c \<name\> and <tt>(a title)</tt>. The nameis the internal identifier that can be used in linking between pages (see\ref commands_miscellaneous for \c \\ref). After you've defined the blockto be a page, you can start writing the contents.For more complicated pages, you might want to divide the page up insections. Use the \c \\section command to define a new section. It takes thesame arguments as \c \\page, namely the \c \<name\> and the<tt>(title)</tt>. If you need a deeper hierarchy you may use \c \\subsectionand \c \\subsubsection, again, both with the same syntax. If you need todistinguish between sections in sub-sub-sections, you are able to use\c \\paragraph, which takes the same arguments.\note Before and after each of the commands above, you need to have an emptyline so as to provide readability. It is not necessary to indentsections and subsections more than the normal two spaces, as long as youkeep the section markers clear.\warning If you are entering the realm of subsections and sub-subsections,think about the nature of your page. Either it needs to be split up intomultiple pages, or what you're writing is too complex and would bebetter off as a big tutorial on the Haiku website.If you are creating multiple pages that are related, you will be able tostructure them in a tree by using the \c \\subpage command. This will rankthe different pages in a tree structure. It will put a link in the place ofthe command, so you should place it at the top of the parent place and useit as an index.\subsection commands_grouping Member Grouping CommandsDoxygen makes it possible to group certain members together. It is usedin the BString class for example, where the members are grouped by what kindof operation they perform, such as appending, finding, etc. Defining groupsis currently not as powerful as it could be, but if you use it insideclasses, you will be fine if you follow the instructions presented inthis section.\note If you are looking on how to add classes to kits, see\ref commands_miscellaneous and have a look at the \c \\ingroup command.Groups of members are preceded by a block that describes what the group isabout. You are required to give each group of members at least a name. Havea look at the example:\verbatim/*!\name Appending MethodsThese methods append things to the object.*///! \@{... methods ...//! \@}\endverbatimThe block preceding the block opening marker, <tt>//! \@{</tt>, contains a\c \\name command and a paragraph that gives a description. The headerblock can be as long or short as you want, but please don't make it toolong. See the \ref style section on how to effectively write group headers.The members that you want to belong to the group are between the groupopening and closing markers.\note Group headers don't have a \c \\brief description.\subsection commands_miscellaneous Miscellaneous CommandsThere are some commands that don't fit into the categories above, but thatyou will end up using every now and then. This section will describe thosecommands.The first one is \c \\n. This command sort of belongs to the category ofmarkup commands. It basically forces a newline. Because Doxygen parsesparagraphs as a single contiguous entity, it's not possible to mark up thetext using carriage returns in the documentation. \c \\n forces a newline inthe output. So in HTML it will be translated into a \c \<br\\\>.Sometimes there are some parts of the API that you don't want to be visible.Since Doxygen extracts all the public and protected members from a class,and virtually every member from a file, you might want to force it to hidecertain things. If so, use the \c \\internal command. If you place this justafter the block marker, the command will be hidden from documentation. Anyfurther documentation or remarks you put inside the block will not bevisible in the final documentation.Images can be a valuable addition to documentation. To include ones youmade, use the \c \\image command. It has the following prototype:<tt>\\image \<format\> \<file\></tt>. The format is currently fixed at\c html. The file refers to the filename relative to the location of thedocumentation file. Any images you want to add should be in the samelocation as the dox file, so only the file name will suffice.Modules are defined in the main book, and you can add classes to them byusing the \c \\ingroup command. This commands adds the class to the moduleand groups it on a separate page. At this moment, the group handling has yetto be finalized. For now, add the classes to the kit they belong in. In thefuture this might change.Finally, it is a good idea to link between parts of the documentation. Thereare two commands for that. The first one is \c \\ref, which enable you torefer to pages, sections, etc. that you created yourself. The second one is\c \\link which refers to members. The first one takes one word as anargument, the name of the section, and it inserts a link with the text ofthe title. \c \\link is more complex. It should always be accompanied by \c\\endlink. The first word between the two commands is the object that isreferred to, and the rest is the link text.\section style Writing GuidelinesThis final section will present guidelines for the actual writing of thedocumentation. Both the structure of the documentation, which sections touse when, and the style of the writing will be discussed. Before diverginginto the requirements for file and class descriptions, member descriptionsand pages, there are some general remarks that apply to all types ofdocumentation.First of all, everything you write should be in <em>proper Englishsentences</em>. Spelling, grammar, punctuation, make sure you adhere to thestandards. It also means the following:- It means that every sentence should at least have asubject and a verb (unless it's an imperative statement).- Also use the proper terminology. Remember, you are dealing with C++here, which means you should use the right names. So use \b methodinstead of function, and data member instead of variable (whereappropriate).- Avoid in-formalism. Avoid constructs like 'if you want todisconnect the object', but rather use 'to disconnect the object'. Avoidfamiliarizes, or jokes.\remarks It isn't the goal to create dry, legal-style documentation. Justtry to find a balance. Read through documentation that's already beenapproved to get a hint of what you should be aiming for.\remarks If you are having a problem with phrasing certain things, put itdown in such a way that it says everything it needs to. A proofreadermight then be able to rephrase it to a better style.Throughout the documentation you might want to provide hints, warnings orremarks that might interrupt the flow of the text, or that need to visuallystand out from the rest. Doxygen provides commands for paragraphs thatdisplay remarks, warnings, notes and points of attention. You can use thesecommands in case you meet one or more of the following requirements:- The point is for a specific audience, such as beginners in the Haiku API.Notes on what to read first, or mistakes that may be made by beginnerswill not be for the entire audience, and such should be separated. Thesekinds of notes should be at the end of blocks.- The point needs to visually stand out. This is especially the case withremarks, but could also apply for other types.- The point is not completely relevant to the text and therefore should beseparated so that it doesn't interrupt the main flow.This listing shows which one to use for which situation:- \c \\attention- Used when the developer is bound to make a mistake, when the API isambiguous. The difference between this and a warning is thatwarnings warn about things that are the developers fault, andattention blocks warn about things that might go wrongbecause of the way the API is structured.- Used to warn for abuse of the API that might be caused by the way theinternals of the system are structured.- \c \\warning- Used to warn developers about using the API in a certain way. Warningsapply especially to new developers that aren't completely familiarwith the API and that might want to abuse it. For example, thethread safety of BString requires a warning.- \c \\note- Used to place references to other documentation that might not bedirectly related to the text. For example, BLooper will have adirect reference to BHandler in the class description, butBMessenger will be mentioned in a note because it does not directlyinfluence the use of the class.- Can also be used for useful hints or notes that somehow need to standout from the rest of the text.- \c \\remarks- Remarks are small notes that would interrupt the flow of the text. Forexample, if you in a text ignore a certain condition that is soextremely rare and uncommon, you can put a remark at the end of thetext to tell that you have been lying.- Remarks interact with the text whereas notes add something unmentionedto it.\subsection style_files File DescriptionsThe design of Doxygen makes it very file oriented, and this might come offas inconvenient. At the moment, how to actually group the documentation isstill under debate, but it does not change the requirement that a headerneeds to be documented before the members of that header can be documented.As such, the first documentation block in your \c dox file will be the blockthat describes the header. Examples:\verbatim/*!\file String.h\brief Defines the BString class and global operators and functions forhandling strings.*//*!\file SupportDefs.h\brief Defines basic types and definitions for the Haiku API.*/\endverbatimThe first statement defines what the block is about, namely the header file.The second element is the \c \\brief remark on what it contains. The firstfile defines the BString class and some global operators. You can see thatreflected in the description. SupportDefs.h does not define classes, butrather a range of different functions and defines, so the text refers tothat.\remarks \\brief documentation for files is about what it \e implements, asheader files are passive (whereas members and functions are active).Thus, use the third person form of the verb.\subsection style_classes Class DescriptionsClasses are the basic building blocks in the Haiku API and as such haveextensive documentation. This section will go over the actual classdescription. This section will present a list of items you should thinkabout when writing the class description. This doesn't mean you'll haveto include every item, it merely serves as a guiding principle that helpsorganise your thoughts. Have a look at the list:-# The \c \\brief description is \b obligatory. This description describeswhat it is. For example, BDataIO: "Abstract interface for objects thatprovide read and write access to data." Note that this description isnot a full sentence, but it does end with a period.-# One or more paragraphs that give a broad overview of what the class cando. Describe things like what it works on, when you want to use it, whatadvantage it might give over other directly related alternatives. Alsodescribe if a class is made to be derived from, and if so, how. Makesure that a developer in the first few paragraphs can judge if what hewants to do can be done with this class.-# One or more paragraphs that show how this class ties in with the restof the kit or the API. What objects does it work with, how it interactswith the servers, etcetera.-# One or more paragraphs that give a concrete example or use case. Keep ittidy and self contained. If you use code examples, make sure yourexamples adhere to Haiku's coding guidelines. Remember, an example canillustrate better than a few paragraphs of text.-# End with a list of references to other classes, functions, pages, etc.that might be of interest to the reader.When documenting classes, don't be too exhaustive. Avoid becoming a tutorialor a complete guide. This documentation is for reference only. If you wantto enlighten the reader on bigger subjects, consider writing a separatedocumentation page that connects the different points you want to make.Also, you don't have to put in any groupings of members in classdescriptions. If you want to do that, physically divide the members up ingroups. Look at the \ref commands_grouping for the actual commands, and at\ref style_groups for help on writing group headers.\subsection style_members Members and FunctionsMembers and functions share the same basic Doxygen syntax, and they can bedocumented in a similar way. That's why this section deals with themtogether. Documenting members is probably the main thing you'll do whenwriting the actual documentation. There are some guidelines as to how, butthe actual implementation probably differs per class. Keep the followingpoints in mind:-# To repeat a very important fact, the first line is a \c \\fn line. Thisline needs to match the declaration, which is in the source file. Thismeans that for members, also the class name and the scope indicator (::)should be present. Also note that this line doesn't have to adhere tothe 80 column width limit.-# The first command is always the \c \\brief command. Give a short andclear description. The description starts with a capital letter and endswith a dot. Don't write the description saying what the method does,like "Starts the timer", but rather as what it will do: "Start thetimer."-# If the brief description doesn't cover all of what the methodor function does, then you can add a few paragraphs that explain it inmore depth. Don't be too verbose, and use an example to illustratepoints. Point out any potential misunderstandings or problems you expectdevelopers to have, but don't repeat the class documentation too much.-# You are obliged to then document all the parameters. Use the \c \\paramcommand for that. For the description, use a short phrase such as "Theoffset (zero based) where to begin the move." Note the capital and thedot.-# If the function is non-void, then you'll have to specify what it willreturn. In case of fixed values, have a look at \c \\retval. You'll usethis one when the return type is a bool or a status_t. In case ofsomething else, use \c \\return. You can also combine these two. Forexample, a method that returns a length (positive) or an error code(negative).-# Use \c \\see if you have any references to other methods, classes orglobal functions. At least document all the overloaded methods. Also addmethods that do the opposite of this method, or methods that areintimately related.In case of overloaded members, you'll need to make a decision. If you needto copy too much information, you might resort to putting it in oneparagraph with the text "This is an overloaded member function, and differsfrom <name> only by the type of parameter it takes." That will keep thecopying down and will point developers right to the place where they can getmore documentation.Again, like class descriptions, you'll have to find a good middle-groundbetween too much information, and too little. Again, write for the broadestaudience possible, and resort to notes and warnings for specialisedaudiences.\subsection style_variables Enumerations, Variables and DefinesThis section helps you document (member) variables and defines that defineconstants, as well as enumerations and their values. If you need to documenta \c \#define macro that takes arguments, have a look at \ref style_membersThe \c \\brief description of all these types follow a similar structure.They are a short phrase that mention what the variable contains. Example:\verbatim/*!\var char* BString::fPrivateData\brief BString's storage for data.This member is deprecated and might even become \c private in futurereleases.If you are planning to derive from this object and you want to manipulatethe raw string data, please have a look at LockBuffer() and UnlockBuffer().*/\endverbatimThe variables you are going to encounter are either \c public or\c protected member variables, or global variables that have a certainsignificance. In the case of member variables, you'll need to document whatthey mean and how the developer should manipulate them. If the class is onethat is meant to be derived from, make sure that in the description of thevariable you mention how it interacts with the others, and how the developershould make sure that the internal coherence of the data and code members ofthe inherited class is maintained.Global variables will mostly be constants. If so, document what they standfor and what they might be used for, as well as which classes and functionsdepend on that constant. If the variable is meant to be changed by thedeveloper, explain what values are valid and which functions and classesdepend on this variable.Defines are usually used as message constants. Give a short description ofwhat the message constant stands for, and where it might be sent from andwhere it might be received.Enumerations can either be anonymous or named. In case of the latter, youcan give a description of the enumeration in a documentation block thatstarts with an \c \\enum command, followed by the name of the enumeration.If the enumeration is within the scope of a class, prepend the classname andthe scope indicator. In case of an anonymous enum, you can only document theindividual members (which you should do for the named enumerations as well),which can be done within code blocks that start with the \c \\var command.Doxygen will know that it's an enumeration value, don't worry about mixups.If the enumeration value is within a class, prepend the classname and scopeindicator. Give a short description of the value, which methods react toit, where it might be used, etcetera. Don't go as far as to copy informationtoo much. For example, if you use an enumeration in only one class and youdocument the possible values there, then don't do that again for theenumeration documentation: rather just refer to it. That sort ofdocumentation belongs to the class description, not to the enumeration.\subsection style_groups GroupsIf you subdivide members of classes into groups, you have the ability toapply some general information that will be listed above the listing of themembers in that group. See the section \ref commands_grouping on how todefine groups. This section is on what to put in the header block.First of all, it's probably a good idea to give your group a name. This namewill be printed as a title and will enhance the clarity of what the groupcontains. If you put the \c \\name command as the first command of a group,the rest of the words on that line will be used as the title. You shouldchoose simple titles of no more than three words.It's possible to add one or two paragraphs of information. These paragraphsshould contain some quick notes on which of the members in that group to usefor what purpose. See it as a quick subdivision that a developer could useas a guide to see which method he actually wants to use. Don't go ondescribing the methods in detail though, that's what the memberdocumentation is about. Have a look at the example:\verbatim/*!\name Comparison MethodsThere are two different comparison methods. First of all there is the wholerange of operators that return a boolean value, secondly there are methodsthat return an integer value, both case sensitive and case insensitive.There are also global comparison operators and global compare functions.You might need these in case you have a sort routine that takes a genericcomparison function, such as BList::SortItems().See the String.h documentation file to see the specifics, as they arebasically the same as implemented in this class.*/\endverbatimStraight, to the point, gives no more information than necessary. Dividesthe members up into two groups and refers to other functions the developermight be looking for. The hard limit is two (short) paragraphs. Using morewill not improve clarity.*/