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

Patch by Alan Smale:

Browse Source 
"I have made the doc header consistent with what the document content
specifies it should be.

I've rephrased things and corrected typos and spelling.

Checked through the grammar and amended some gramatical errors."

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21103 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
2007-05-10 09:02:45 +00:00
parent d1c9c9d4b4
commit 5625684593
1 changed files with 188 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/apidoc.dox
+184 -188
View File
@@ -1,68 +1,63 @@
// /*
// Copyright 2007 Haiku Inc. All rights reserved. * Copyright 2007 Haiku Inc. All rights reserved.
// * Distributed under the terms of the MIT License.
// Distributed under the terms of the MIT License. *
// * Documentation by:
// * Niels Sascha Reedijk <[email protected]>
// Documentation by: */
// Niels Sascha Reedijk <[email protected]>
//
/*! /*!
\page apidoc Documenting the API \page apidoc Documenting the API
This article explains how to document the API. It's intended audience are the This article explains how to document the API. Its intended audience are the
Haiku developers that want to document their own classes, and also the Haiku developers who want to document their own classes, and also the members
members of the API Documentation team who want to brush up the documentation. 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 describes the demands that are made from the markup and spacing of the files.
spacing of the files. \ref commands describes the subset \ref commands describes the subset of Doxygen commands the Haiku API
of Doxygen commands the Haiku API documentation uses, and which commands documentation uses, and which commands are used in which situation. \ref style
are used in which situation. \ref style describes the describes the required style and structure of the documentation.
writing style that is required. The demands are both on the required sections
in the documentation as well as on the wording of that 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 documentation for the API documentation team to go over, have a good look at
at the formal requirements and the doxygen commands, and have a quick glance the formal requirements and the Doxygen commands. In addition, have a quick
at how to write member and class documentation, since you'll need to know glance at how to write member and class documentation, since you'll need to
which information should definately be in the documentation. Aspiring members know which information is mandatory for the documentation. Aspiring members or
or members of the API documentation team should read the third section members of the API documentation team should read the third section carefully,
carefully, and should also check out some of the finished documentation to and should also check out some of the finished documentation to get a good
get a good grip on the actual tone, style and contents of the documentation. 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 like
and how to put delimeters to separate different 'blocks' in your source file. 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, Doxygen, the tool that we use to generate the marked up documentation, has an
has an ingenious parser that is able to scan through both header and source ingenious parser that is able to scan through both header and source files
files and that makes it possible to document the API directly in the headers making it possible to document the API directly in the headers or the source.
or the source. However, the Haiku project decided not to put the However, the Haiku project have decided not to put the documentation in either
documentation in either location, and opt for the third option Doxygen gives: location, and opt for the third option Doxygen provides: to put the
to put the documentation in separate files. documentation into separate files.
\note The reasons to not put the \note The reasons to not put the documentation in the header files are
documentation in the header files are twofold. First of all, it would twofold. First of all, it would add unnecessary cruft to the headers that
unnecesarily add much cruft to the headers that the compiler will have to the compiler will needlessly have to parse. File access and speed isn't BeOS
parse unneededly. File access and speed isn't BeOS and Haiku's best quality. and Haiku's best quality. The second reason is that the system headers are
The second reason is that the system headers are included throughout the included throughout the tree. It's a waste of electricity to have everybody
tree. It's a waste of electricity to have everybody recompile the entire tree recompile the entire tree if someone fixes a typo in the documentation.
if someone fixes a typo in the documentation. Likewise, the reason to not put Likewise, the reason to not put the documentation in the source code is that
the documentation in the source is that it unnecesarily clutters up that it unnecessarily clutters up that file. By not using direct documentation we
source. By not using direct documentation we lose some advantages, like the lose some advantages, like the fact that developers might be inclined to
fact that developers might be inclined to update the documentation quicker update the documentation quicker if they change a method, but as you will
if they change a method, but as you will see we'll have some methods in place see we'll have some methods in place to prevent that to a certain extent.
to prevent that to a certain extend.
There are a few aspects to naming and location 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 not only
means that they get the same name, but also that the order of the methods, means that they get the same name, but also that the order of the methods,
variables, functions, etc. will have to be the same. 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 /trunk/headers/os.
In a similar vein, the root of the documentation files is at In a similar vein, the root of the documentation files is at
@@ -75,12 +70,12 @@
\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 with the revision copyright block, with a reference to the author(s) and against which revision
against which the documentaton was written. the documentation was written.
\verbatim \verbatim
/* /*
* Copyright 2007 Haiku, Inc. All rights reserved. * Copyright 2007 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Documentation by: * Documentation by:
@@ -88,15 +83,15 @@
* 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 are enclosed between -# The header is put in a standard C comment, which is enclosed between
\c /* and \c *\/. \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>Documentation space. If the text is part of a category, such as <tt>Documentation
by</tt>, put three spaces after the delimeter. by</tt>, put three spaces after the delimiter.
-# We start with a copyright notice. The first line is empty, then the -# We start with a copyright notice. The first line is empty, then the
copyright notice, then the line on \e MIT, followed by an empty line. copyright notice, then the line on \e MIT, followed by an empty line.
-# Then there is a label <tt>Documentation by:</tt>, which is followed by -# Then there is a label <tt>Documentation by:</tt>, which is followed by
@@ -104,23 +99,23 @@
-# The final part is underneath the label <tt>Corresponds to:</tt>. -# The final part is underneath the label <tt>Corresponds to:</tt>.
Underneath there is a list of files and their svn revisions that the Underneath there is a list of files and their svn revisions that the
current documentation is known to correspond with. current documentation is known to correspond with.
-# The header block ends with the \c *\/, where the asterix is alligned with -# The header block ends with the \c *\/, where the asterix is aligned with
with the ones above it. the ones above it.
\subsection formalrequirements_blocks Blocks \subsection formalrequirements_blocks Blocks
Blocks are the basic units of documentation for Doxygen. At first it will Blocks are the basic units of documentation for Doxygen. At first it will feel
feel like overkill to use blocks, but realize that Doxygen was initially like overkill to use blocks, but realize that Doxygen was initially designed
designed to operate on header and source files, and then the blocks of to operate on header and source files, and then the blocks of documentation
documentation would be before the definition or declaration of the would be before the definition or declaration of the methods, functions,
methods, functions, etcetera. Doxygen is used to blocks and that's why we etcetera. Doxygen is used to operating on blocks, and that's why we need to
need to reproduce them in our \c dox files. 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 in between these markers. -# The documentation is placed in between these markers.
-# All the contents in between the markers is indended by two spaces. -# All the contents in between the markers is indented by two spaces.
-# The maximum width of contents between blocks is 80 columns. <em>Try not -# 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. to cross this limit</em>, because it will severely limit readability.
Example: Example:
@@ -133,41 +128,40 @@
\retval true The item was appended. \retval true The item was appended.
\retval false Item was not appended, since resizing the list failed. \retval false Item was not appended, since resizing the list failed.
\sa AddItem(void *item, int32 index) \sa AddItem(void *item, int32 index)
* / */
\endverbatim \endverbatim
\note Doxygen also allows to use single line comments, starting with \c //!, \note Doxygen also allows the use of single line comments, starting with
however, we won't use these \b except in case of group markers, which you \c //!, however, we won't use these \b except for group markers, which you
can read more about in the next section. can read more about in the next section.
\subsection formalrequirements_delimeters Delimeters \subsection formalrequirements_delimiters Delimiters
Many of the header files in the Haiku API just document one class or one Many of the header files in the Haiku API just document one class or one group
group of functions. However, there might want to come a time that you come of functions. However, there be a time when you come across a more complex
across a more complex header and for the sake of clarity of your \c dox file header and for the sake of clarity in your \c dox file you want to mark the
you want to mark the sections. Use the standard delimiter marker for this, sections. Use the standard delimiter marker for this, which consists of five
which consists of five slashes, a space, the title of the section, a space slashes, a space, the title of the section, a space and another five slashes.
and another five slashes. Like this: <tt>///// Global Functions /////</tt>. 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 This section describes all the Doxygen commands that will be used in the Haiku
Haiku API documentation. As a rule, Doxygen commands start with a backslash API documentation. As a rule, Doxygen commands start with a backslash (\\) and
(\\) and are followed by whitespace (such as a space or a newline), with the are followed by whitespace (such as a space or a newline), with the exception
exception of group markers, which will be discussed later on. The commands of group markers; this is discussed in more detail later on. The commands can
can be divided into several categories, which will be described in the be divided into several categories, which are described in the following
following subsections. 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
on that. This section merely explains the different groupings and for that. This section merely explains the different groupings and
syntaxes of commands. syntaxes of commands.
Most commands accept an argument. Arguments can be either of these three Most commands accept an argument. Arguments can be one of these three types:
types:
- \<single_word\> - The argument is a single word. - \<single_word\> - The argument is a single word.
- (until the end of the line) - The argument runs until the end of the line. - (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 is - {paragraph} - The argument runs for an entire paragraph. A paragraph is
@@ -187,8 +181,8 @@
documentation block would be one of the following commands: documentation block would be one of the following commands:
- \c \\class \<name\> \n - \c \\class \<name\> \n
Tells doxygen that the following section is going to be on Tells Doxygen that the following section is going to be on the class as
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 given
declaration. Please note that the declaration is what you find in the source declaration. Please note that the declaration is what you find in the source
@@ -203,7 +197,7 @@
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 declaration.
Copy the declaration exactly, including the leading \c typedef keyword. 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.
@@ -214,7 +208,7 @@
\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 recuring sections in the documentation. Documentation that belongs there are recurring sections in the documentation. Documentation that belongs
to a certain section should be placed after a command that marks the start to a certain section should be placed after a command that marks the start
of that section. All the commands take a paragraph as answer. A paragraph of that section. All the commands take a paragraph as answer. A paragraph
ends with a whitespace, or with a command that marks a new section. Note that ends with a whitespace, or with a command that marks a new section. Note that
@@ -223,11 +217,11 @@
following: following:
- \c \\brief {brief description} \n - \c \\brief {brief description} \n
This is the only \b obligatory section. Every member should have at least This is the only \b mandatory section. Every member should have at least
a brief description. a brief description.
- \c \\param \<parameter-name\> {parameter description} \n - \c \\param \<parameter-name\> {parameter description} \n
This section describes a parameter with the name \a parameter-name. The This section describes a parameter with the name \a parameter-name. The
parameter name must match the function declaration, since doxygen will parameter name must match the function declaration, since Doxygen will
check if all the documented parameters exist. check if all the documented parameters exist.
- \c \\return {description of the return value} \n - \c \\return {description of the return value} \n
This section describes the return value. This is a totally free form This section describes the return value. This is a totally free form
@@ -238,7 +232,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 which one to use when. documentation. See the style section to find out the appropriate situations in
which to use them.
- \c \\note {text} - \c \\note {text}
- \c \\attention {text} - \c \\attention {text}
@@ -247,19 +242,19 @@
\subsection commands_markup Markup \subsection commands_markup Markup
Sometimes you might certain text to have a special markup, to make words Sometimes you might require certain text to have a special markup, to make
stand out, but also if you want to have example code within the documentation words stand out, but also if you want to have example code within the
you'll need a special markup. Doxygen defines three types of commands. documentation you'll need a special markup. Doxygen defines three types of
There are commands that work on single words, commands that work on longer commands. There are commands that work on single words, commands that work on
phrases and commands that define blocks. Basically, the single letter longer phrases and commands that define blocks. Basically, the single letter
commands are commands that work on a the next word. If you need to mark commands are commands that work on a the next word. If you need to mark
multiple words or sentences, use the HTML-style commands. Finally, for multiple words or sentences, use the HTML-style commands. Finally, for blocks
blocks of code or blocks of text that need to be in "typewriter" font, use of code or blocks of text that need to be in "typewriter" font, use the block
the block commands. Have a look at the listing: 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
when refering to parameters in method descriptions. when referring to parameters in method descriptions.
- <b>Bold text</b> - <b>Bold text</b>
- For single words, use \c \\b. - For single words, use \c \\b.
- For multiple words, enclose between the \c \<b\> and \c \<\\b\> tags. - For multiple words, enclose between the \c \<b\> and \c \<\\b\> tags.
@@ -268,11 +263,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 two - The commands \c \\verbatim and \c \\endverbatim. Everything between these
commands will be put in a distinct block that stands out from the rest of the two commands will be put in a distinct block that stands out from the rest
text. of the text.
- The commands \c \\code and \c \\endcode do the same, but Doxygen will parse the - The commands \c \\code and \c \\endcode do the same, but Doxygen will
contents and try to mark up the code to make it look just a bit nicer. parse the contents and try to mark up the code to make it look a 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.
@@ -284,7 +280,7 @@
since they're not members, some of the structuring commands won't work. 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, so Important to know is that a page is the complete length of the block, so
dividing it up in subsections by starting new blocks will not work. Instead, dividing it up in subsections by starting new blocks will not work. Instead,
doxygen provides some commands to structure text on a page. Doxygen provides some commands to structure text on a page.
First of all, you define a new page by using the \c \\page command. This First of all, you define a new page by using the \c \\page command. This
command takes two arguments: a \c \<name\> and <tt>(a title)</tt>. The name command takes two arguments: a \c \<name\> and <tt>(a title)</tt>. The name
@@ -295,17 +291,17 @@
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 sections.
Use the \c \\section command to define a new section. It takes the same Use the \c \\section command to define a new section. It takes the same
arguments as \c \\page, namely the \c \<name\> and the <tt>(title)</tt>. If arguments as \c \\page, namely the \c \<name\> and the <tt>(title)</tt>. If
you need a deeper hierarchy you may sue \c \\subsection and you need a deeper hierarchy you may use \c \\subsection and
\c \\subsubsection, again, both with the same syntax. If you need to \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 for readability. It is not necessary to indent sections and subsections line so as to provide readability. It is not necessary to indent sections
more than the normal two spaces, as long as you keep the section markers and subsections more than the normal two spaces, as long as you keep the
clear. section markers clear.
\warning If you are entering the realm of subsections and subsubsections, \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 better
off as a big tutorial on the Haiku website. off as a big tutorial on the Haiku website.
@@ -327,7 +323,7 @@
\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.
Groups of members are preceeded by a block that describes what the group is Groups of members are preceded by a block that describes what the group is
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:
@@ -336,7 +332,7 @@
\\name Appending Methods \\name Appending Methods
These methods append things to the object. These methods append things to the object.
* / */
//! \@{ //! \@{
@@ -345,12 +341,12 @@
//! \@} //! \@}
\endverbatim \endverbatim
The block preceeding 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 block
can be as long or short as you want, but please don't make it too long. See can be as long or short as you want, but please don't make it too long. See
the \ref style section on how to effectively write group headers. The the \ref style section on how to effectively write group headers. The
members that you want to belong to the group are between the group opening members that you want to belong to the group are between the group opening
and closure markers. and closing markers.
\note Group headers don't have a \c \\brief description. \note Group headers don't have a \c \\brief description.
@@ -361,10 +357,10 @@
commands. commands.
The first one is \c \\n. This commands sort of belongs to the category of The first one is \c \\n. This commands sort of belongs to the category of
markup commands. It basically forces a newline. Because doxygen parses markup commands. It basically forces a newline. Because Doxygen parses
paragraphs as continuous, it's not possible to mark up the text using returns paragraphs as a single contiguous entity, it's not possible to mark up the
in the documentation. \c \\n forces a newline in the output. So in HTML it text using carriage returns in the documentation. \c \\n forces a newline in
will be translated into a \c \<br\\\>. the 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. 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, Since Doxygen extracts all the public and protected members from a class,
@@ -383,8 +379,8 @@
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
and groups it on a separate page. At this moment, the group handling is till and groups it on a separate page. At this moment, the group handling has yet
to be worked out. For now, add the classes to the kit they belong in. In the to be finalised. For now, add the classes to the kit they belong in. In the
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
@@ -399,10 +395,11 @@
\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 documentation. Both the structure of the documentation, which sections to use
use when, and the style of the writing will be discussed. Before diverging when, and the style of the writing will be discussed. Before diverging into
into the requirements for file and class descriptions, member descriptions and pages, the requirements for file and class descriptions, member descriptions and
there are some general remarks that apply to all types of documentation. pages, there are some general remarks that apply to all types of
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
sentences</em>. Spelling, grammar, punctuation, make sure you adhere to the sentences</em>. Spelling, grammar, punctuation, make sure you adhere to the
@@ -418,35 +415,35 @@
\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 at. 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 might
be able to put it in better words. 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
stand out from the rest. Doxygen provides commands for paragraphs that stand out from the rest. Doxygen provides commands for paragraphs that
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 point is for a specific audience, such as beginners in the Haiku API.
the Haiku API. Notes on what to read first, or mistakes that can be made Notes on what to read first, or mistakes that may be made by beginners will
by beginners will not be for the entire audience, and such should be not be for the entire audience, and such should be separated. These kinds of
separated. These kinds of notes should be at the end of blocks. 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
separated so that it doesn't interrupt the main flow. separated so that it doesn't interrupt the main flow.
This listing shows which one to use when: 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 to a warning is that warnings warn for things ambiguous. The difference between this and a warning is that warnings warn
that are the developer's fault, and attention blocks warn for things that about things that are the developers fault, and attention blocks warn
might go wrong because of the way the API is structured. 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 for 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 with
the API and that might want to abuse it. For example, the thread safety the API and that might want to abuse it. For example, the thread safety
of BString requires a warning. of BString requires a warning.
@@ -458,13 +455,13 @@
the class. 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.
- Remarks interact with the text, notes add something unmentioned to it.
- \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 extremely
rare and uncommon, you can put a remark at the end of the text to tell rare and uncommon, you can put a remark at the end of the text to tell
that you have been lying. that you have been lying.
- Remarks interact with the text, notes add something unmentioned to it. - Remarks interact with the text whereas notes add something unmentioned to
it.
\subsection style_files File Descriptions \subsection style_files File Descriptions
@@ -480,20 +477,19 @@
\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 rather a range of different functions and defines, so the text refers to that.
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). Thus,
@@ -501,12 +497,12 @@
\subsection style_classes Class Descriptions \subsection style_classes Class Descriptions
Classes are the basic building blocks in the Haiku API and as such will 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 about
when writing the class description. This doesn't mean you'll have to put when writing the class description. This doesn't mean you'll have to include
every item in, it merely serves as a guiding principle that helps organise every item, it merely serves as a guiding principle that helps organise your
your thoughts. Have a look at the list: 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
@@ -519,13 +515,13 @@
sure that a developer in the first few paragraphs can judge if what he sure that a developer in the first few paragraphs can judge if what he
wants to do can be done with this class. wants to do can be done with this class.
-# One or more paragraphs that show how this class ties in with the rest -# One or more paragraphs that show how this class ties in with the rest
of the kit or the API. What objects does it work with, how does it interact 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 selfcontained. Remember, an example can tell more than a few tidy and self contained. Remember, an example can illustrate better than a
paragraphs of text. few paragraphs of text.
-# End with a list of references to other classes, functions, pages, etc. -# End with a list of references to other classes, functions, pages, etc. that
might be of interest for the reader. 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 to
@@ -539,7 +535,7 @@
\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 together.
Documenting members is probably the main thing you'll do when writing the Documenting members is probably the main thing you'll do when writing the
actual documentation. There are some guidelines as to how, but the actual actual documentation. There are some guidelines as to how, but the actual
@@ -554,9 +550,9 @@
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 timer."
-# If the brief description doesn't cover all the method or function does, -# If the brief description doesn't cover all of what the method or function
then you can add a few paragraphs that explain it in more depth. Don't be does, then you can add a few paragraphs that explain it in more depth. Don't
to verbose, and use an example to illustrate points. Point out any be too verbose, and use an example to illustrate points. Point out any
potential misunderstandings or problems you expect developers to have, but potential misunderstandings or problems you expect developers to have, but
don't repeat the class documentation too much. 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
@@ -566,17 +562,18 @@
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 something
else, use \c \\return. You can also combine these two. For example, a else, use \c \\return. You can also combine these two. For example, a
method that returns a lenght (positive) or an error code (negative). 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 intimately
related. related.
In case of overloaded members, you'll need to make a decision. If you need In case of overloaded members, you'll need to make a decision. If you need to
to copy too much information, you might resort to put in one paragraph with copy too much information, you might resort to putting it in one paragraph
the text "This is an overloaded member function, and differs from \<name\> only with the text "This is an overloaded member function, and differs from
by the type of parameter it takes." That will keep the copying down and will \<name\> only by the type of parameter it takes." That will keep the copying
point developers right to the place where they can get more documentation. down and will point developers right to the place where they can get 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
@@ -586,32 +583,32 @@
\subsection style_variables Enumerations, Variables and Defines \subsection style_variables Enumerations, Variables and Defines
This section helps you document (member) variables and defines that define This section helps you document (member) variables and defines that define
constant, 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 mentions 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 go \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 raw If you are planning to derive from this object and you want to manipulate the
string data, please have a look at LockBuffer() and UnlockBuffer(). 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
significance. In the case of member variables, you'll need to document what significance. In the case of member variables, you'll need to document what
they mean and how the developer should manipulate it. If the class is one they mean and how the developer should manipulate them. If the class is one
that is meant to be derived from, make sure that in the that is meant to be derived from, make sure that in the description of the
description of the variable you mention how it interacts with the others, and variable you mention how it interacts with the others, and how the developer
how the developer should make sure that the internal coherence of the data should make sure that the internal coherence of the data and code members of
and code members of the inherited class is maintained. the inherited class is maintained.
Global variables will mostly be constants. If so, document what they stand Global variables will mostly be constants. If so, document what they stand
for and what they might be used for, as well as which classes and functions for and what they might be used for, as well as which classes and functions
@@ -641,39 +638,38 @@
\subsection style_groups Groups \subsection style_groups Groups
If you subdivide members of classes into groups, you have the ability to If you subdivide members of classes into groups, you have the ability to apply
apply some general information that will be listed above the listing of the some general information that will be listed above the listing of the members
members in that group. See the section \ref commands_grouping on how to in that group. See the section \ref commands_grouping on how to define groups.
define groups. This section is on what to put in the header block. 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
contains. If you put the \c \\name command as the first command of a contains. If you put the \c \\name command as the first command of a group,
group, the rest of the words on that line will be used as title. You should the rest of the words on that line will be used as the title. You should
chose simple titles, no more than three words. choose simple titles of no more than three words.
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 cause. See it as a quick subdivision which a developer could use for what purpose. See it as a quick subdivision that a developer could use as
as a guide to see which method he actually wants to use. Don't go on a guide to see which method he actually wants to use. Don't go on describing
describing the methods in detail though, that's what the member documentation the methods in detail though, that's what the member documentation is about.
is about. Have a look at the example: Have a look at the example:
\verbatim \verbatim
/*! /*!
\name Comparison Methods \name Comparison Methods
There are two different comparison methods. First of all there There are two different comparison methods. First of all there is the whole
is the whole range of operators that return a boolean value, secondly range of operators that return a boolean value, secondly there are methods
there are methods that return an integer value, both case sensitive that return an integer value, both case sensitive and case insensitive.
and case insensitive.
There are also global comparison operators and global compare functions. There are also global comparison operators and global compare functions.
You might need these in case you have a sort routine that takes a generic You might need these in case you have a sort routine that takes a generic
comparison function, such as BList::SortItems(). comparison function, such as BList::SortItems().
See the String.h documentation file to see the specifics, though basically See the String.h documentation file to see the specifics, as they are
there are 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