- Document each class, function, and enum in the header
files.
- The one exception is that functions in derived objects do not
need to be documented if the documentation is inherited from
the base class. This should be tested in Doxygen to be sure that it
works correctly.
- Here's an example of documented a class. Note the formatting of
the comments. It's a C-style comment. The open comment marker
(
/*) is followed by an exclamation mark to indicate that
it's a Doxygen comment. The open and close comment markers are on
lines by themselves, and the text of the comment is indented two
spaces. Always include a \brief description. The long
description follows. Observe the use of the formatting tags
\c and \e. The \note tag is
used for any special notes. The \author tag is
recommended.
/*!
\brief Arbitrary combination of status tests.
In the \c AND (see NOX::Status::Combo::ComboType) combination, the
result is \c Unconverged (see NOX::Status::StatusType) if \e any of
the tests is \c Unconverged. Otherwise, the result is equal to the
result of the \e first test in the list that is either \c Converged
or \c Failed. It is not recommended to mix \c Converged and \c
Failed tests in an \c AND combination.
In the \c OR combination, the result is \c Unconverged if \e all of
the tests are \c Unconverged. Otherwise, it is the result of the \e
first test in the list that is either \c Converged or \c
Failed. Therefore, it will generally make sense to put the \c Failed
-type tests at the end of the \c OR list.
\note We always runs through all tests, even if we don't need
to. This is useful so that the user knows which tests have and have
not be satisfied.
\author Tammy Kolda (SNL 8950)
*/
class Combo : public Test {
...
}; // class Combo
- Any parameters that are used within the class must be
documented in the class description and in the file NOX_Description.H on the parameters "page".
Note that the name, a brief description, and the default value for
each parameter is listed.
/*!
\brief %Newton-like solver with a line search.
The following parameters are valid for this solver:
- "Line Search" - Sublist of the line search parameters, passed to
the NOX::Linesearch::Factory. Defaults to an empty list.
- "Linear Solver" - Sublist of the linear solver parameters, passed
to Abstract::Group::computeNewton(). Furthermore, the "Tolerance"
within this list may be modified by the
resetForcingTerm(). Defaults to an empty list.
- "Forcing Term Method" - Method to compute the forcing term, i.e.,
the tolerance for the linear solver. Defaults to ""
(nothing). Choices are "Type 1" and "Type 2".
- "Forcing Term Minimum Tolerance" - Minimum acceptable linear
solver tolerance. Defaults to 1.0e-6.
- "Forcing Term Maximum Tolerance" = Maximum acceptable linear
solver tolerance. Default to 0.01.
- "Forcing Term Alpha" - Used for the "Type 2" forcing term
calculation. Defaults to 1.5.
- "Forcing Term Gamma" - Used for the "Type 2" forcing term
calculation. Defaults to 0.9.
\author Tammy Kolda (SNL 8950), Roger Pawlowski (SNL 9233)
*/
Here's a more complicated example to produce a two-tiered list.
/*!
The parameters must specify the type of line search as well as all
the corresponding parameters for that line search.
<ul>
<li> "Method" - Name of the line search. Valid choices are
<ul>
<li> "Full Step" (NOX::Linesearch::FullStep)
<li> "Interval %Halving" (NOX::Linesearch::Halving)
<li> "Polynomial" (NOX::Linesearch::Polynomial)
<li> "More'-Thuente" (NOX::Linesearch::MoreThuente)
</ul>
</ul>
*/
- Constants and enums can generally be described with simple
\brief comments. Those can be formatted in either of two
ways, as follows.
/*!
\brief The test can be either the AND of all the component
tests, or the OR of all the component tests.
*/
enum ComboType {AND, OR};
//! Constructor
Combo(ComboType t = OR);
- Doxygen does automatically cross-linking, which is very
convenient. However, sometimes it cross-links when you don't intend
for it to. For example, the following line would automatically
generate a link from the word
Newton to the
NOX::Solver::Newton class.
//! Newton-like solver with a line search.
To prevent that automatic link, insert a percent sign (%)
immediately before the word that is causing the link. For example,
//! %Newton-like solver with a line search.
