i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the API guidelines to make them more consistent with the coding

Browse Source 
guidelines. Three new guidelines:
- Commas between names and email adresses in header blocks.
- Indent with tabs (with lenght 4)
- Two whitelines between blocks


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21832 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
2007-08-06 09:09:29 +00:00
parent 2aacca4469
commit ff3d9bfa2a
1 changed files with 707 additions and 687 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/apidoc.dox
+281 -261
View File
@@ -1,105 +1,110 @@
/* /*
* Copyright 2007 Haiku Inc. All rights reserved. * Copyright 2007 Niels Sascha Reedijk. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk, [email protected]
* Proofreaders: * Proofreaders:
* Alan Smale <[email protected]> * Alan Smale, [email protected]
*/ */
/*! /*!
\page apidoc Documenting the API \page apidoc Documenting the API
This article explains how to document the API. Its intended audience are the This article explains how to document the API. Its intended audience are the
Haiku developers who want to document their own classes, and also the members Haiku developers who want to document their own classes, and also the
of the API Documentation team who want to brush up the documentation. members of the API Documentation team who want to brush up the
documentation.
This document is divided into three sections. \ref formalrequirements This document is divided into three sections. \ref formalrequirements
describes the demands that are made from the markup and spacing of the files. describes the demands that are made from the markup and spacing of the
\ref commands describes the subset of Doxygen commands the Haiku API files. \ref commands describes the subset of Doxygen commands the Haiku API
documentation uses, and which commands are used in which situation. \ref style documentation uses, and which commands are used in which situation. \ref
describes the required style and structure of the documentation. style describes the required style and structure of the documentation. If
you are a developer and you want to prepare the first version of the
If you are a developer and you want to prepare the first version of the
documentation for the API documentation team to go over, have a good look at documentation for the API documentation team to go over, have a good look at
the formal requirements and the Doxygen commands. In addition, have a quick the formal requirements and the Doxygen commands. In addition, have a quick
glance at how to write member and class documentation, since you'll need to glance at how to write member and class documentation, since you'll need to
know which information is mandatory for the documentation. Aspiring members or know which information is mandatory for the documentation. Aspiring members
members of the API documentation team should read the third section carefully, or members of the API documentation team should read the third section
and should also check out some of the finished documentation to get a good carefully, and should also check out some of the finished documentation to
grip on the actual tone, style and contents of the documentation. get a good grip on the actual tone, style and contents of the documentation.
\section formalrequirements Formal Requirements \section formalrequirements Formal Requirements
This section describes formal requirements, such as location and naming of This section describes formal requirements, such as location and naming of
the files, the header blocks of files, what blocks of documentation look like the files, the header blocks of files, what blocks of documentation look
and how to put delimiters to separate different 'blocks' in your source file. like and how to put delimiters to separate different 'blocks' in your source
file.
\subsection formalrequirements_location Location of the Documentation Source \subsection formalrequirements_location Location of the Documentation Source
Doxygen, the tool that we use to generate the marked up documentation, has an Doxygen, the tool that we use to generate the marked up documentation, has
ingenious parser that is able to scan through both header and source files an ingenious parser that is able to scan through both header and source
making it possible to document the API directly in the headers or the source. files making it possible to document the API directly in the headers or the
However, the Haiku project have decided not to put the documentation in either source. However, the Haiku project have decided not to put the documentation
location, and opt for the third option Doxygen provides: to put the in either location, and opt for the third option Doxygen provides: to put
documentation into separate files. the documentation into separate files.
\note The reasons to not put the documentation in the header files are \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 twofold. First of all, it would add unnecessary cruft to the headers
the compiler will needlessly have to parse. File access and speed isn't BeOS that the compiler will needlessly have to parse. File access and speed
and Haiku's best quality. The second reason is that the system headers are isn't BeOS and Haiku's best quality. The second reason is that the
included throughout the tree. It's a waste of electricity to have everybody system headers are included throughout the tree. It's a waste of
recompile the entire tree if someone fixes a typo in the documentation. electricity to have everybody recompile the entire tree if someone fixes
Likewise, the reason to not put the documentation in the source code is that a typo in the documentation. Likewise, the reason to not put the
it unnecessarily clutters up that file. By not using direct documentation we documentation in the source code is that it unnecessarily clutters up
lose some advantages, like the fact that developers might be inclined to that file. By not using direct documentation we lose some advantages,
update the documentation quicker if they change a method, but as you will like the fact that developers might be inclined to update the
see we'll have some methods in place to prevent that to a certain extent. documentation quicker if they change a method, but as you will see we'll
have some methods in place to prevent that to a certain extent.
There are a few aspects to the naming and locations of files: There are a few aspects to the naming and locations of files:
-# Most important, documentation files \b mirror header files. This not only -# Most important, documentation files \b mirror header files. This
means that they get the same name, but also that the order of the methods, not only means that they get the same name, but also that the order
variables, functions, etc. will have to be the same. of the methods, variables, functions, etc. will have to be the same.
-# The root directory of the public API headers is at \c /trunk/headers/os. -# The root directory of the public API headers is at \c
In a similar vein, the root of the documentation files is at /trunk/headers/os. In a similar vein, the root of the documentation
\c /trunk/src/documentation/haiku_book. The subdirectory structure, or files is at \c /trunk/src/documentation/haiku_book. The subdirectory
the division of kits, will also be replicated. structure, 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 name of the files is the same as the base of the header files,
the \c dox extension. So \c Something.h becomes \c Something.dox. Note with the \c dox extension. So \c Something.h becomes \c
the case! Something.dox. Note the case!
\subsection formalrequirements_headerblock The Header Block \subsection formalrequirements_headerblock The Header Block
Every documentation file will begin with the header block. It's basically a Every documentation file will begin with the header block. It's basically a
copyright block, with a reference to the author(s) and against which revision copyright block, with a reference to the author(s) and against which
the documentation was written. revision the documentation was written.
\verbatim \verbatim
/* /*
* Copyright 2007 Haiku Inc. All rights reserved. * Copyright 2007 Niels Sascha Reedijk. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk, [email protected]
* Proofreaders: * Proofreaders:
* Alan Smale <[email protected]> * Alan Smale, [email protected]
* Corresponds to: * Corresponds to:
* /trunk/headers/os/support/String.h rev 19731 * /trunk/headers/os/support/String.h rev 19731
* /trunk/src/kits/support/String.cpp rev 19731 * /trunk/src/kits/support/String.cpp rev 19731
*/ */
\endverbatim \endverbatim
The example above has a few elements that you should take note of: The 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 -# The header is put in a standard C comment, which is enclosed between \c
\c /* and \c *\/. /* and \c *\/.
-# Every line starts with a whitespace and an asterix, followed by another -# Every line starts with a whitespace and an asterix, followed by another
space. If the text is part of a category, such as <tt>Authors</tt>, put space. If the text is part of a category, such as <tt>Authors</tt>, put
three spaces after the delimiter. three spaces after the delimiter.
-# We start with a copyright notice. The first line is empty, then the -# The first line is empty, then we get to the copyright notice. You may
copyright notice, then the line on \e MIT, followed by an empty line. either retain the copyright yourself, or you can attribute to to Haiku
Inc. It's your choice. The next line is the \e MIT licence notice,
followed by an empty line.
-# Then there is a label <tt>Authors:</tt>, which is followed by -# Then there is a label <tt>Authors:</tt>, which is followed by
lines with names and email addresses between brackets. lines with names and email addresses. The latter one is optional, but
recommended.
-# In the same vein there is the label <tt>Proofreaders:</tt> in case the -# In the same vein there is the label <tt>Proofreaders:</tt> in case the
file has been proofread. file has been proofread.
-# The final part is underneath the label <tt>Corresponds to:</tt>. -# The final part is underneath the label <tt>Corresponds to:</tt>.
@@ -110,19 +115,22 @@
\subsection formalrequirements_blocks Blocks \subsection formalrequirements_blocks Blocks
Blocks are the basic units of documentation for Doxygen. At first it will feel Blocks are the basic units of documentation for Doxygen. At first it will
like overkill to use blocks, but realize that Doxygen was initially designed feel like overkill to use blocks, but realize that Doxygen was initially
to operate on header and source files, and then the blocks of documentation designed to operate on header and source files, and then the blocks of
would be before the definition or declaration of the methods, functions, documentation would be before the definition or declaration of the methods,
etcetera. Doxygen is used to operating on blocks, and that's why we need to functions, etcetera. Doxygen is used to operating on blocks, and that's why
reproduce them in our \c dox files. we need to reproduce them in our \c dox files.
Blocks should adhere to the following standards: Blocks should adhere to the following standards:
-# All blocks open with \c /*! and close with \c * / -# All blocks open with \c /*! and close with \c * /
-# The documentation is placed in between these markers. -# The documentation is placed in between these markers.
-# All the contents in between the markers is indented by two spaces. -# All the contents in between the markers is indented by tabs. The tab
-# The maximum width of the contents between blocks is 80 columns. <em>Try not length should be four.
to cross this limit</em>, because it will severely limit readability. -# Between blocks, there should be two empty lines.
-# The maximum width of the contents between blocks is 80 columns. <em>Try
not to cross this limit</em>, because it will severely limit
readability.
Example: Example:
\verbatim \verbatim
@@ -138,34 +146,34 @@
\endverbatim \endverbatim
\note Doxygen also allows the use of single line comments, starting with \note Doxygen also allows the use of single line comments, starting with
\c //!, however, we won't use these \b except for group markers, which you \c //!, however, we won't use these \b except for group markers, which
can read more about in the next section. you can read more about in the next section.
\subsection formalrequirements_delimiters Delimiters \subsection formalrequirements_delimiters Delimiters
Many of the header files in the Haiku API just document one class or one group Many of the header files in the Haiku API just document one class or one
of functions. However, there be a time when you come across a more complex group of functions. However, there be a time when you come across a more
header and for the sake of clarity in your \c dox file you want to mark the complex header and for the sake of clarity in your \c dox file you want to
sections. Use the standard delimiter marker for this, which consists of five mark the sections. Use the standard delimiter marker for this, which
slashes, a space, the title of the section, a space and another five slashes. consists of five slashes, a space, the title of the section, a space and
Like this: <tt>///// Global Functions /////</tt>. another five slashes. Like this: <tt>///// Global Functions /////</tt>.
\note This is only for the source files and for you as documenter. It will \note This is only for the source files and for you as documenter. It will
not show up in the actual generated documentation! not show up in the actual generated documentation!
\section commands Doxygen Commands \section commands Doxygen Commands
This section describes all the Doxygen commands that will be used in the Haiku This section describes all the Doxygen commands that will be used in the
API documentation. As a rule, Doxygen commands start with a backslash (\\) and Haiku API documentation. As a rule, Doxygen commands start with a backslash
are followed by whitespace (such as a space or a newline), with the exception (\\) and are followed by whitespace (such as a space or a newline), with the
of group markers; this is discussed in more detail later on. The commands can exception of group markers; this is discussed in more detail later on. The
be divided into several categories, which are described in the following commands can be divided into several categories, which are described in the
subsections. following subsections.
\note This section does not discuss which commands you should actually use \note This section does not discuss which commands you should actually use
in documentation. See the next section on \ref style in documentation. See the next section on \ref style for that. This
for that. This section merely explains the different groupings and section merely explains the different groupings and syntaxes of
syntaxes of commands. commands.
Most commands accept an argument. Arguments can be one of these three types: Most commands accept an argument. Arguments can be one of these three types:
- \<single_word\> - The argument is a single word. - \<single_word\> - The argument is a single word.
@@ -174,10 +182,10 @@
ended by an empty line, or if another command that defines a \ref ended by an empty line, or if another command that defines a \ref
commands_sections sections is found. Note that if you use commands that commands_sections sections is found. Note that if you use commands that
work on a paragraph and you split it over multiple lines (because of the work on a paragraph and you split it over multiple lines (because of the
maximum line width of 80 characters or because it looks better), you will maximum line width of 80 characters or because it looks better), you
have to indent subsequent lines that belong to the paragraph with two more will have to indent subsequent lines that belong to the paragraph with
spaces, making the total of four. This is to visually distinguish two more spaces, making the total of four. This is to visually
paragraphs for other documenters. distinguish paragraphs for other documenters.
\subsection commands_definitions Block Definitions \subsection commands_definitions Block Definitions
@@ -190,23 +198,25 @@
Tells Doxygen that the following section is going to be on the class as Tells Doxygen that the following section is going to be on the class as
specified by \a name. specified by \a name.
- \c \\fn (function declaration) \n - \c \\fn (function declaration) \n
This block is going to be about the function that corresponds to the given This block is going to be about the function that corresponds to the
declaration. Please note that the declaration is what you find in the source given declaration. Please note that the declaration is what you find in
file, so if class members are declared, the classname and the scope operator, the source file, so if class members are declared, the classname and the
\c ::, are to be added as well. Modifiers such as \c const should be scope operator, \c ::, are to be added as well. Modifiers such as \c
included. const should be included.
- \c \\var (variable declaration) \n - \c \\var (variable declaration) \n
This block is going to be about the variable indicated by the declaration. This block is going to be about the variable indicated by the
This means basically that data members of a class should have the classname declaration. This means basically that data members of a class should
and the scope operator as well. have the classname and the scope operator as well.
- \c \\typedef (typedef declaration) \n - \c \\typedef (typedef declaration) \n
This block is going to be about the typedef indicated by the declaration. This block is going to be about the typedef indicated by the
Copy the declaration exactly, including the leading \c typedef keyword. declaration. Copy the declaration exactly, including the leading \c
typedef keyword.
- \c \\struct \<name\> \n - \c \\struct \<name\> \n
Tells Doxygen the section is going to be on the \c struct indicated by Tells Doxygen the section is going to be on the \c struct indicated by
\a name. \a name.
- \c \\def \<name\> \n - \c \\def \<name\> \n
This block is going to be about the \c \#define with the identifier \a name. This block is going to be about the \c \#define with the identifier \a
name.
- \c \\page \n - \c \\page \n
This block represents a page. See the section on \ref commands_pages for This block represents a page. See the section on \ref commands_pages for
detailed information on pages. detailed information on pages.
@@ -214,13 +224,13 @@
\subsection commands_sections Sections in Member Documentation \subsection commands_sections Sections in Member Documentation
If you have a look at the output that Doxygen generates, you can see that If you have a look at the output that Doxygen generates, you can see that
there are recurring sections in the documentation. Documentation that belongs there are recurring sections in the documentation. Documentation that
to a certain section should be placed after a command that marks the start belongs to a certain section should be placed after a command that marks the
of that section. All the commands take a paragraph as answer. A paragraph start of that section. All the commands take a paragraph as answer. A
ends with a whitespace, or with a command that marks a new section. Note that paragraph ends with a whitespace, or with a command that marks a new
this list only shows the syntax of the commands. For the semantics, have a section. Note that this list only shows the syntax of the commands. For the
look at the next section on style. In member documentation you can use the semantics, have a look at the next section on style. In member documentation
following: you can use the following:
- \c \\brief {brief description} \n - \c \\brief {brief description} \n
This is the only \b mandatory section. Every member should have at least This is the only \b mandatory section. Every member should have at least
@@ -238,8 +248,8 @@
This section contains references to other parts of the documentation. This section contains references to other parts of the documentation.
There are also a number of things that can be used in pages and member There are also a number of things that can be used in pages and member
documentation. See the style section to find out the appropriate situations in documentation. See the style section to find out the appropriate situations
which to use them. in which to use them.
- \c \\note {text} - \c \\note {text}
- \c \\attention {text} - \c \\attention {text}
@@ -251,12 +261,12 @@
Sometimes you might require certain text to have a special markup, to make Sometimes you might require certain text to have a special markup, to make
words stand out, but also if you want to have example code within the words stand out, but also if you want to have example code within the
documentation you'll need a special markup. Doxygen defines three types of documentation you'll need a special markup. Doxygen defines three types of
commands. There are commands that work on single words, commands that work on commands. There are commands that work on single words, commands that work
longer phrases and commands that define blocks. Basically, the single letter on longer phrases and commands that define blocks. Basically, the single
commands are commands that work on a the next word. If you need to mark letter commands are commands that work on a the next word. If you need to
multiple words or sentences, use the HTML-style commands. Finally, for blocks mark multiple words or sentences, use the HTML-style commands. Finally, for
of code or blocks of text that need to be in "typewriter" font, use the block blocks of code or blocks of text that need to be in "typewriter" font, use
commands. Have a look at the following listing: the block commands. Have a look at the following listing:
- \c \\a \n - \c \\a \n
Use to refer to parameters or arguments in a running text, for example Use to refer to parameters or arguments in a running text, for example
@@ -269,12 +279,12 @@
a monospace, or typewriter, font. There are a few options a monospace, or typewriter, font. There are a few options
- \c \\c for single words. - \c \\c for single words.
- \c \<tt\> and \c \<\\tt\> for multiple words or phrases - \c \<tt\> and \c \<\\tt\> for multiple words or phrases
- The commands \c \\verbatim and \c \\endverbatim. Everything between these - The commands \c \\verbatim and \c \\endverbatim. Everything between
two commands will be put in a distinct block that stands out from the rest these two commands will be put in a distinct block that stands out
of the text. from the rest of the text.
- The commands \c \\code and \c \\endcode do the same, but Doxygen will - The commands \c \\code and \c \\endcode do the same, but Doxygen will
parse the contents and try to mark up the code to make it look a little bit parse the contents and try to mark up the code to make it look a
nicer. little bit nicer.
- <em>Emphasis</em> - <em>Emphasis</em>
- \c \\e for single words. - \c \\e for single words.
- \c \<em\> and \c \<\\em\> for phrases. - \c \<em\> and \c \<\\em\> for phrases.
@@ -294,23 +304,23 @@
\ref commands_miscellaneous for \c \\ref). After you've defined the block \ref commands_miscellaneous for \c \\ref). After you've defined the block
to be a page, you can start writing the contents. to be a page, you can start writing the contents.
For more complicated pages, you might want to divide the page up in sections. For more complicated pages, you might want to divide the page up in
Use the \c \\section command to define a new section. It takes the same sections. Use the \c \\section command to define a new section. It takes the
arguments as \c \\page, namely the \c \<name\> and the <tt>(title)</tt>. If same arguments as \c \\page, namely the \c \<name\> and the
you need a deeper hierarchy you may use \c \\subsection and <tt>(title)</tt>. If you need a deeper hierarchy you may use \c \\subsection
\c \\subsubsection, again, both with the same syntax. If you need to and \c \\subsubsection, again, both with the same syntax. If you need to
distinguish between sections in subsubsections, you are able to use distinguish between sections in subsubsections, you are able to use
\c \\paragraph, which takes the same arguments. \c \\paragraph, which takes the same arguments.
\note Before and after each of the commands above, you need to have an empty \note Before and after each of the commands above, you need to have an empty
line so as to provide readability. It is not necessary to indent sections line so as to provide readability. It is not necessary to indent
and subsections more than the normal two spaces, as long as you keep the sections and subsections more than the normal two spaces, as long as you
section markers clear. keep the section markers clear.
\warning If you are entering the realm of subsections and sub-subsections, \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 into think about the nature of your page. Either it needs to be split up into
multiple pages, or what you're writing is too complex and would be better multiple pages, or what you're writing is too complex and would be
off as a big tutorial on the Haiku website. better off as a big tutorial on the Haiku website.
If you are creating multiple pages that are related, you will be able to If you are creating multiple pages that are related, you will be able to
structure them in a tree by using the \c \\subpage command. This will rank structure them in a tree by using the \c \\subpage command. This will rank
@@ -323,8 +333,9 @@
Doxygen makes it possible to group certain members together. It is used Doxygen makes it possible to group certain members together. It is used
in the BString class for example, where the members are grouped by what kind in the BString class for example, where the members are grouped by what kind
of operation they perform, such as appending, finding, etc. Defining groups of operation they perform, such as appending, finding, etc. Defining groups
is currently not as powerful as it could be, but if you use it inside classes, is currently not as powerful as it could be, but if you use it inside
you will be fine if you follow the instructions presented in this section. classes, you will be fine if you follow the instructions presented in
this section.
\note If you are looking on how to add classes to kits, see \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. \ref commands_miscellaneous and have a look at the \c \\ingroup command.
@@ -333,26 +344,27 @@
about. You are required to give each group of members at least a name. Have about. You are required to give each group of members at least a name. Have
a look at the example: a look at the example:
\verbatim \verbatim
/*! /*!
\\name Appending Methods \\name Appending Methods
These methods append things to the object. These methods append things to the object.
*/ */
//! \@{ //! \@{
... names of the methods ... ... names of the methods ...
//! \@} //! \@}
\endverbatim \endverbatim
The block preceding the block opening marker, <tt>//! \@{</tt>, contains a The block preceding the block opening marker, <tt>//! \@{</tt>, contains a
\c \\name command and a paragraph that gives a description. The header block \c \\name command and a paragraph that gives a description. The header
can be as long or short as you want, but please don't make it too long. See block can be as long or short as you want, but please don't make it too
the \ref style section on how to effectively write group headers. The long. See the \ref style section on how to effectively write group headers.
members that you want to belong to the group are between the group opening The members that you want to belong to the group are between the group
and closing markers. opening and closing markers.
\note Group headers don't have a \c \\brief description. \note Group headers don't have a \c \\brief description.
@@ -373,15 +385,15 @@
and virtually every member from a file, you might want to force it to hide and virtually every member from a file, you might want to force it to hide
certain things. If so, use the \c \\internal command. If you place this just certain things. If so, use the \c \\internal command. If you place this just
after the block marker, the command will be hidden from documentation. Any after the block marker, the command will be hidden from documentation. Any
further documentation or remarks you put inside the block will not be visible further documentation or remarks you put inside the block will not be
in the final documentation. visible in the final documentation.
Images can be a valuable addition to documentation. To include ones you made, Images can be a valuable addition to documentation. To include ones you
use the \c \\image command. It has the following prototype: made, use the \c \\image command. It has the following prototype:
<tt>\\image \<format\> \<file\></tt>. The format is currently fixed at <tt>\\image \<format\> \<file\></tt>. The format is currently fixed at
\c html. The file refers to the filename relative to the location of the \c html. The file refers to the filename relative to the location of the
documentation file. Any images you want to add should be in the same location documentation file. Any images you want to add should be in the same
as the dox file, so only the file name will suffice. location 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 by Modules are defined in the main book, and you can add classes to them by
using the \c \\ingroup command. This commands adds the class to the module using the \c \\ingroup command. This commands adds the class to the module
@@ -390,21 +402,21 @@
future this might change. future this might change.
Finally, it is a good idea to link between parts of the documentation. There Finally, it is a good idea to link between parts of the documentation. There
are two commands for that. The first one is \c \\ref, which enable you to refer are two commands for that. The first one is \c \\ref, which enable you to
to pages, sections, etc. that you created yourself. The second one is \c \\link refer to pages, sections, etc. that you created yourself. The second one is
which refers to members. The first one is takes one word as an argument, the \c \\link which refers to members. The first one is takes one word as an
name of the section, and it inserts a link with the name of the title. \c \\link argument, the name of the section, and it inserts a link with the name of
is more complex. It should always be accompanied by \c \\endlink. The first the title. \c \\link is more complex. It should always be accompanied by \c
word between the two commands is the object that is referred to, and the \\endlink. The first word between the two commands is the object that is
rest is the link text. referred to, and the rest is the link text.
\section style Writing Guidelines \section style Writing Guidelines
This final section will present guidelines for the actual writing of the This final section will present guidelines for the actual writing of the
documentation. Both the structure of the documentation, which sections to use documentation. Both the structure of the documentation, which sections to
when, and the style of the writing will be discussed. Before diverging into use when, and the style of the writing will be discussed. Before diverging
the requirements for file and class descriptions, member descriptions and into the requirements for file and class descriptions, member descriptions
pages, there are some general remarks that apply to all types of and pages, there are some general remarks that apply to all types of
documentation. documentation.
First of all, everything you write should be in <em>proper English First of all, everything you write should be in <em>proper English
@@ -413,18 +425,19 @@
- It means that every sentence should at least have a - It means that every sentence should at least have a
subject and a verb (unless it's an imperative statement). subject and a verb (unless it's an imperative statement).
- Also use the proper terminology. Remember, you are dealing with C++ - Also use the proper terminology. Remember, you are dealing with C++
here, which means you should use the right names. So use \b method instead here, which means you should use the right names. So use \b method
of function, and data member instead of variable (where appropriate). instead of function, and data member instead of variable (where
- Avoid informalism. Avoid constructs like 'if you want to disconnect the appropriate).
object', but rather use 'to disconnect the object'. Avoid familiarisms, or - Avoid informalism. Avoid constructs like 'if you want to
jokes. disconnect the object', but rather use 'to disconnect the object'. Avoid
familiarisms, or jokes.
\remarks It isn't the goal to create dry, legal-style documentation. Just \remarks It isn't the goal to create dry, legal-style documentation. Just
try to find a balance. Read through documentation that's already been try to find a balance. Read through documentation that's already been
approved to get a hint of what you should be aiming for. approved to get a hint of what you should be aiming for.
\remarks If you are having a problem with phrasing certain things, put it \remarks If you are having a problem with phrasing certain things, put it
down in such a way that it says everything it needs to. A proofreader might down in such a way that it says everything it needs to. A proofreader
then be able to rephrase it to a better style. might then be able to rephrase it to a better style.
Throughout the documentation you might want to provide hints, warnings or Throughout the documentation you might want to provide hints, warnings or
remarks that might interrupt the flow of the text, or that need to visually remarks that might interrupt the flow of the text, or that need to visually
@@ -432,9 +445,9 @@
display remarks, warnings, notes and points of attention. You can use these display remarks, warnings, notes and points of attention. You can use these
commands in case you meet one or more of the following requirements: commands 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. - 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 beginners will Notes on what to read first, or mistakes that may be made by beginners
not be for the entire audience, and such should be separated. These kinds of will not be for the entire audience, and such should be separated. These
notes should be at the end of blocks. kinds of notes should be at the end of blocks.
- The point needs to visually stand out. This is especially the case with - The point needs to visually stand out. This is especially the case with
remarks, but could also apply for other types. remarks, but could also apply for other types.
- The point is not completely relevant to the text and therefore should be - The point is not completely relevant to the text and therefore should be
@@ -443,77 +456,80 @@
This listing shows which one to use for which situation: This listing shows which one to use for which situation:
- \c \\attention - \c \\attention
- Used when the developer is bound to make a mistake, when the API is - Used when the developer is bound to make a mistake, when the API is
ambiguous. The difference between this and a warning is that warnings warn ambiguous. The difference between this and a warning is that
about things that are the developers fault, and attention blocks warn warnings warn about things that are the developers fault, and
about things that might go wrong because of the way the API is structured. attention blocks warn about things that might go wrong
because of the way the API is structured.
- Used to warn for abuse of the API that might be caused by the way the - Used to warn for abuse of the API that might be caused by the way the
internals of the system are structured. internals of the system are structured.
- \c \\warning - \c \\warning
- Used to warn developers about using the API in a certain way. Warnings - Used to warn developers about using the API in a certain way. Warnings
apply especially to new developers that aren't completely familiar with apply especially to new developers that aren't completely familiar
the API and that might want to abuse it. For example, the thread safety with the API and that might want to abuse it. For example, the
of BString requires a warning. thread safety of BString requires a warning.
- \c \\note - \c \\note
- Used to place references to other documentation that might not be - Used to place references to other documentation that might not be
directly related to the text. For example, BLooper will have a direct directly related to the text. For example, BLooper will have a
reference to BHandler in the class description, but BMessenger will be direct reference to BHandler in the class description, but
mentioned in a note because it does not directly influence the use of BMessenger will be mentioned in a note because it does not directly
the class. influence the use of the class.
- Can also be used for useful hints or notes that somehow need to stand - Can also be used for useful hints or notes that somehow need to stand
out from the rest of the text. out from the rest of the text.
- \c \\remarks - \c \\remarks
- Remarks are small notes that would interrupt the flow of the text. For - Remarks are small notes that would interrupt the flow of the text. For
example, if you in a text ignore a certain condition that is so extremely example, if you in a text ignore a certain condition that is so
rare and uncommon, you can put a remark at the end of the text to tell extremely rare and uncommon, you can put a remark at the end of the
that you have been lying. text to tell that you have been lying.
- Remarks interact with the text whereas notes add something unmentioned to - Remarks interact with the text whereas notes add something unmentioned
it. to it.
\subsection style_files File Descriptions \subsection style_files File Descriptions
The design of Doxygen makes it very file oriented, and this might come off as The design of Doxygen makes it very file oriented, and this might come off
inconvenient. At the moment, how to actually group the documentation is still as inconvenient. At the moment, how to actually group the documentation is
under debate, but it does not change the requirement that a header needs to still under debate, but it does not change the requirement that a header
be documented before the members of that header can be documented. As such, needs to be documented before the members of that header can be documented.
the first documentation block in your \c dox file will be the block that As such, the first documentation block in your \c dox file will be the block
describes the header. Examples: that describes the header. Examples:
\verbatim \verbatim
/*! /*!
\file String.h \file String.h
\brief Defines the BString class and global operators and functions for \brief Defines the BString class and global operators and functions for
handling strings. handling strings.
*/ */
/*! /*!
\file SupportDefs.h \file SupportDefs.h
\brief Defines basic types and definitions for the Haiku API. \brief Defines basic types and definitions for the Haiku API.
*/ */
\endverbatim \endverbatim
The first statement defines what the block is about, namely the header file. The 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 first The second element is the \c \\brief remark on what it contains. The first
file defines the BString class and some global operators. You can see that file defines the BString class and some global operators. You can see that
reflected in the description. SupportDefs.h does not define classes, but reflected in the description. SupportDefs.h does not define classes, but
rather a range of different functions and defines, so the text refers to that. rather a range of different functions and defines, so the text refers to
that.
\remarks \\brief documentation for files is about what it \e implements, as \remarks \\brief documentation for files is about what it \e implements, as
header files are passive (whereas members and functions are active). Thus, header files are passive (whereas members and functions are active).
use the third person form of the verb. Thus, use the third person form of the verb.
\subsection style_classes Class Descriptions \subsection style_classes Class Descriptions
Classes are the basic building blocks in the Haiku API and as such have Classes are the basic building blocks in the Haiku API and as such have
extensive documentation. This section will go over the actual class extensive documentation. This section will go over the actual class
description. This section will present a list of items you should think about description. This section will present a list of items you should think
when writing the class description. This doesn't mean you'll have to include about when writing the class description. This doesn't mean you'll have
every item, it merely serves as a guiding principle that helps organise your to include every item, it merely serves as a guiding principle that helps
thoughts. Have a look at the list: organise your thoughts. Have a look at the list:
-# The \c \\brief description is \b obligatory. This description describes -# The \c \\brief description is \b obligatory. This description describes
what it is. For example, BDataIO: "Abstract interface for objects that what it is. For example, BDataIO: "Abstract interface for objects that
provide read and write access to data." Note that this description is not provide read and write access to data." Note that this description is
a full sentence, but it does end with a period. not a full sentence, but it does end with a period.
-# One or more paragraphs that give a broad overview of what the class can -# One or more paragraphs that give a broad overview of what the class can
do. Describe things like what it works on, when you want to use it, what do. Describe things like what it works on, when you want to use it, what
advantage it might give over other directly related alternatives. Also advantage it might give over other directly related alternatives. Also
@@ -524,29 +540,30 @@
of the kit or the API. What objects does it work with, how it interacts of the kit or the API. What objects does it work with, how it interacts
with the servers, etcetera. with the servers, etcetera.
-# One or more paragraphs that give a concrete example or use case. Keep it -# One or more paragraphs that give a concrete example or use case. Keep it
tidy and self contained. If you use code examples, make sure your examples tidy and self contained. If you use code examples, make sure your
adhere to Haiku's coding guidelines. Remember, an example can illustrate examples adhere to Haiku's coding guidelines. Remember, an example can
better than a few paragraphs of text. illustrate better than a few paragraphs of text.
-# End with a list of references to other classes, functions, pages, etc. that -# End with a list of references to other classes, functions, pages, etc.
might be of interest to the reader. that might be of interest to the reader.
When documenting classes, don't be to exhaustive. Avoid becoming a tutorial When documenting classes, don't be to exhaustive. Avoid becoming a tutorial
or a complete guide. This documentation is for reference only. If you want to or a complete guide. This documentation is for reference only. If you want
enlighten the reader on bigger subjects, consider writing a separate to enlighten the reader on bigger subjects, consider writing a separate
documentation page that connects the different points you want to make. documentation page that connects the different points you want to make.
Also, you don't have to put in any groupings of members in class descriptions. Also, you don't have to put in any groupings of members in class
If you want to do that, physically divide the members up in groups. Look at descriptions. If you want to do that, physically divide the members up in
the \ref commands_grouping for the actual commands, and at \ref style_groups groups. Look at the \ref commands_grouping for the actual commands, and at
for help on writing group headers. \ref style_groups for help on writing group headers.
\subsection style_members Members and Functions \subsection style_members Members and Functions
Members and functions share the same basic Doxygen syntax, and they can be Members and functions share the same basic Doxygen syntax, and they can be
documented in a similar way. That's why this section deals with them together. documented in a similar way. That's why this section deals with them
Documenting members is probably the main thing you'll do when writing the together. Documenting members is probably the main thing you'll do when
actual documentation. There are some guidelines as to how, but the actual writing the actual documentation. There are some guidelines as to how, but
implementation probably differs per class. Keep the following points in mind: the actual implementation probably differs per class. Keep the following
points in mind:
-# To repeat a very important fact, the first line is a \c \\fn line. This -# To repeat a very important fact, the first line is a \c \\fn line. This
line needs to match the declaration, which is in the source file. This line needs to match the declaration, which is in the source file. This
@@ -556,31 +573,33 @@
-# The first command is always the \c \\brief command. Give a short and -# The first command is always the \c \\brief command. Give a short and
clear description. The description starts with a capital letter and ends clear description. The description starts with a capital letter and ends
with a dot. Don't write the description saying what the method does, with a dot. Don't write the description saying what the method does,
like "Starts the timer", but rather as what it will do: "Start the timer." like "Starts the timer", but rather as what it will do: "Start the
-# If the brief description doesn't cover all of what the method or function timer." -# If the brief description doesn't cover all of what the method
does, then you can add a few paragraphs that explain it in more depth. Don't or function does, then you can add a few paragraphs that explain it in
be too verbose, and use an example to illustrate points. Point out any more depth. Don't be too verbose, and use an example to illustrate
potential misunderstandings or problems you expect developers to have, but points. Point out any potential misunderstandings or problems you expect
don't repeat the class documentation too much. developers to have, but don't repeat the class documentation too much.
-# You are obliged to then document all the parameters. Use the \c \\param -# You are obliged to then document all the parameters. Use the \c \\param
command for that. For the description, use a short phrase such as "The command for that. For the description, use a short phrase such as "The
offset (zero based) where to begin the move." Note the capital and the dot. offset (zero based) where to begin the move." Note the capital and the
dot.
-# If the function is non-void, then you'll have to specify what it will -# If the function is non-void, then you'll have to specify what it will
return. In case of fixed values, have a look at \c \\retval. You'll use return. In case of fixed values, have a look at \c \\retval. You'll use
this one when the return type is a bool or a status_t. In case of something this one when the return type is a bool or a status_t. In case of
else, use \c \\return. You can also combine these two. For example, a something else, use \c \\return. You can also combine these two. For
method that returns a length (positive) or an error code (negative). example, a method that returns a length (positive) or an error code
(negative).
-# Use \c \\see if you have any references to other methods, classes or -# Use \c \\see if you have any references to other methods, classes or
global functions. At least document all the overloaded methods. Also add global functions. At least document all the overloaded methods. Also add
methods that do the opposite of this method, or methods that are intimately methods that do the opposite of this method, or methods that are
related. intimately related.
In case of overloaded members, you'll need to make a decision. If you need to In case of overloaded members, you'll need to make a decision. If you need
copy too much information, you might resort to putting it in one paragraph to copy too much information, you might resort to putting it in one
with the text "This is an overloaded member function, and differs from paragraph with the text "This is an overloaded member function, and differs
\<name\> only by the type of parameter it takes." That will keep the copying from \<name\> only by the type of parameter it takes." That will keep the
down and will point developers right to the place where they can get more copying down and will point developers right to the place where they can get
documentation. more documentation.
Again, like class descriptions, you'll have to find a good middle-ground Again, like class descriptions, you'll have to find a good middle-ground
between too much information, and too little. Again, write for the broadest between too much information, and too little. Again, write for the broadest
@@ -591,22 +610,23 @@
This section helps you document (member) variables and defines that define This section helps you document (member) variables and defines that define
constants, as well as enumerations and their values. If you need to document constants, as well as enumerations and their values. If you need to document
a \c \#define macro that takes arguments, have a look at \ref style_members . a \c \#define macro that takes arguments, have a look at \ref style_members
The \c \\brief description of all these types follow a similar structure. The \c \\brief description of all these types follow a similar structure.
They are a short phrase that mention what the variable contains. Example: They are a short phrase that mention what the variable contains. Example:
\verbatim \verbatim
/*! /*!
\var char* BString::fPrivateData \var char* BString::fPrivateData
\brief BString's storage for data. \brief BString's storage for data.
This member is deprecated and might even become \c private in future releases. This member is deprecated and might even become \c private in future
releases.
If you are planning to derive from this object and you want to manipulate the If you are planning to derive from this object and you want to manipulate
raw string data, please have a look at LockBuffer() and UnlockBuffer(). the raw string data, please have a look at LockBuffer() and UnlockBuffer().
*/ */
\endverbatim \endverbatim
The variables you are going to encounter are either \c public or The variables you are going to encounter are either \c public or
\c protected member variables, or global variables that have a certain \c protected member variables, or global variables that have a certain
@@ -627,28 +647,28 @@
what the message constant stands for, and where it might be send from and what the message constant stands for, and where it might be send from and
where it might be received. where it might be received.
Enumerations can either be anonymous or named. In case of the latter, you can Enumerations can either be anonymous or named. In case of the latter, you
give a description of the enumeration in a documentation block that starts can give a description of the enumeration in a documentation block that
with an \c \\enum command, followed by the name of the enumeration. If the starts with an \c \\enum command, followed by the name of the enumeration.
enumeration is within the scope of a class, prepend the classname and the If the enumeration is within the scope of a class, prepend the classname and
scope indicator. In case of an anonymous enum, you can only document the the scope indicator. In case of an anonymous enum, you can only document the
individual members (which you should do for the named enumerations as well), individual 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. 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. 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 scope If the enumeration value is within a class, prepend the classname and scope
indicator. Give a short description of the value, which methods react to it, indicator. Give a short description of the value, which methods react to
where it might be used, etcetera. Don't go as far as to copy information too it, where it might be used, etcetera. Don't go as far as to copy information
much. For example, if you use an enumeration in only one class and you too much. For example, if you use an enumeration in only one class and you
document the possible values there, then don't do that again for the document the possible values there, then don't do that again for the
enumeration documentation: rather just refer to it. That sort of documentation enumeration documentation: rather just refer to it. That sort of
belongs to the class description, not to the enumeration. documentation belongs to the class description, not to the enumeration.
\subsection style_groups Groups \subsection style_groups Groups
If you subdivide members of classes into groups, you have the ability to apply If you subdivide members of classes into groups, you have the ability to
some general information that will be listed above the listing of the members apply some general information that will be listed above the listing of the
in that group. See the section \ref commands_grouping on how to define groups. members in that group. See the section \ref commands_grouping on how to
This section is on what to put in the header block. define 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 name First of all, it's probably a good idea to give your group a name. This name
will be printed as a title and will enhance the clarity of what the group will be printed as a title and will enhance the clarity of what the group
@@ -658,12 +678,12 @@
It's possible to add one or two paragraphs of information. These paragraphs It's possible to add one or two paragraphs of information. These paragraphs
should contain some quick notes on which of the members in that group to use should contain some quick notes on which of the members in that group to use
for what purpose. See it as a quick subdivision that a developer could use as for what purpose. See it as a quick subdivision that a developer could use
a guide to see which method he actually wants to use. Don't go on describing as a guide to see which method he actually wants to use. Don't go on
the methods in detail though, that's what the member documentation is about. describing the methods in detail though, that's what the member
Have a look at the example: documentation is about. Have a look at the example:
\verbatim \verbatim
/*! /*!
\name Comparison Methods \name Comparison Methods
@@ -677,7 +697,7 @@
See the String.h documentation file to see the specifics, as they are See the String.h documentation file to see the specifics, as they are
basically the same as implemented in this class. basically the same as implemented in this class.
*/ */
\endverbatim \endverbatim
Straight, to the point, gives no more information than necessary. Divides Straight, to the point, gives no more information than necessary. Divides
the members up into two groups and refers to other functions the developer the members up into two groups and refers to other functions the developer