Skip to content
Snippets Groups Projects
Commit a3d18c64 authored by Henry's avatar Henry
Browse files

codingStyleGuide: Added more details about Doxygen documentation

parent 4275e01b
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/codingStyleGuide.org
+ 155
− 96
View file @ a3d18c64
......@@ -24,23 +24,23 @@
+ stream output
+ =<<= is always four characters after the start of the stream,
so that the =<<= symbols align, i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC c++
Info<< ...
os << ...
#+END_EXAMPLE
#+END_SRC
so
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
#+END_SRC
+ no unnecessary class section headers, i.e. remove
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
// Check
......@@ -48,37 +48,96 @@
// Edit
// Write
#+END_EXAMPLE
#+END_SRC
if they contain nothing, even if planned for 'future use'
+ class titles are centred
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
#+END_SRC
NOT
*not*
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
#+END_SRC
*** The /.H/ Files
+ header file spacing
+ Leave two empty lines between sections
(as per functions in the /.C/ file etc)
+ use =//- Comment= comments in header file
+ add descriptions to class data and functions
+ use =//- Comment= comments in header file to add descriptions to class
data and functions do be included in the Doxygen documentation:
+ text on the line starting with =//-= becomes the Doxygen brief
description;
+ text on subsequent lines becomes the Doxygen detailed description /e.g./
#+BEGIN_SRC C++
//- A function which returns a thing
// This is a detailed description of the function
// which processes stuff and returns other stuff
// depending on things.
thing function(stuff1, stuff2);
#+END_SRC
+ list entries start with =-= or =-#= for numbered lists but cannot start
on the line immediately below the brief description so
#+BEGIN_SRC C++
//- Compare triFaces
// Returns:
// - 0: different
// - +1: identical
// - -1: same face, but different orientation
static inline int compare(const triFace&, const triFace&);
#+END_SRC
or
#+BEGIN_SRC C++
//- Compare triFaces returning 0, +1 or -1
//
// - 0: different
// - +1: identical
// - -1: same face, but different orientation
static inline int compare(const triFace&, const triFace&);
#+END_SRC
*not*
#+BEGIN_SRC C++
//- Compare triFaces returning 0, +1 or -1
// - 0: different
// - +1: identical
// - -1: same face, but different orientation
static inline int compare(const triFace&, const triFace&);
#+END_SRC
+ list can be nested for example
#+BEGIN_SRC C++
//- Search for \em name
// in the following hierarchy:
// -# personal settings:
// - ~/.OpenFOAM/\<VERSION\>/
// <em>for version-specific files</em>
// - ~/.OpenFOAM/
// <em>for version-independent files</em>
// -# site-wide settings:
// - $WM_PROJECT_INST_DIR/site/\<VERSION\>
// <em>for version-specific files</em>
// - $WM_PROJECT_INST_DIR/site/
// <em>for version-independent files</em>
// -# shipped settings:
// - $WM_PROJECT_DIR/etc/
//
// \return the full path name or fileName() if the name cannot be found
// Optionally abort if the file cannot be found
fileName findEtcFile(const fileName&, bool mandatory=false);
#+END_SRC
+ for more details see the Doxygen documentation.
+ destructor
+ If adding a comment to the destructor -
use =//-= and code as a normal function:
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
//- Destructor
~className();
#+END_EXAMPLE
#+END_SRC
+ inline functions
+ Use inline functions where appropriate in a separate /classNameI.H/
file. Avoid cluttering the header file with function bodies.
......@@ -86,23 +145,23 @@
*** The /.C/ Files
+ Do not open/close namespaces in a /.C/ file
+ Fully scope the function name, i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
Foam::returnType Foam::className::functionName()
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
namespace Foam
{
...
returnType className::functionName()
...
}
#+END_EXAMPLE
#+END_SRC
EXCEPTION
When there are multiple levels of namespace, they may be used in the
/.C/ file, i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
namespace Foam
{
namespace compressible
......@@ -113,7 +172,7 @@
} // End namespace RASModels
} // End namespace compressible
} // End namespace Foam
#+END_EXAMPLE
#+END_SRC
+ Use two empty lines between functions
......@@ -123,25 +182,25 @@
+ const
+ Use everywhere it is applicable.
+ variable initialisation using
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
const className& variableName = otherClass.data();
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
const className& variableName(otherClass.data());
#+END_EXAMPLE
#+END_SRC
+ virtual functions
+ If a class is virtual, make all derived classes virtual.
*** Conditional Statements
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
if (condition)
{
code;
}
#+END_EXAMPLE
#+END_SRC
OR
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
if
(
long condition
......@@ -149,24 +208,24 @@
{
code;
}
#+END_EXAMPLE
NOT (no space between =if= and =(= used)
#+BEGIN_EXAMPLE
#+END_SRC
*not* (no space between =if= and =(= used)
#+BEGIN_SRC C++
if(condition)
{
code;
}
#+END_EXAMPLE
#+END_SRC
*** =for= and =while= Loops
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
for (i = 0; i < maxI; i++)
{
code;
}
#+END_EXAMPLE
#+END_SRC
OR
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
for
(
i = 0;
......@@ -176,26 +235,26 @@
{
code;
}
#+END_EXAMPLE
NOT this (no space between =for= and =(= used)
#+BEGIN_EXAMPLE
#+END_SRC
*not* this (no space between =for= and =(= used)
#+BEGIN_SRC C++
for(i = 0; i < maxI; i++)
{
code;
}
#+END_EXAMPLE
#+END_SRC
Note that when indexing through iterators, it is often slightly more
efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=
*** =forAll=, =forAllIter=, =forAllConstIter=, etc. loops
like =for= loops, but
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
forAll(
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
forAll (
#+END_EXAMPLE
#+END_SRC
Using the =forAllIter= and =forAllConstIter= macros is generally
advantageous - less typing, easier to find later. However, since
they are macros, they will fail if the iterated object contains
......@@ -203,9 +262,9 @@
The following will FAIL!:
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
#+END_EXAMPLE
#+END_SRC
These convenience macros are also generally avoided in other
container classes and OpenFOAM primitive classes.
......@@ -214,106 +273,106 @@
+ split initially after the function return type and left align
+ do not put =const= onto its own line - use a split to keep it with
the function name and arguments.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
#+END_SRC
*nor*
#+BEGIN_SRC C++
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
#+END_SRC
*nor*
#+BEGIN_SRC C++
const Foam::longReturnTypeName& Foam::longClassName::
longFunctionName const
#+END_EXAMPLE
#+END_SRC
+ if it needs to be split again, split at the function name (leaving
behind the preceding scoping =::=s), and again, left align, i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const
#+END_EXAMPLE
#+END_SRC
***** Splitting long lines at an "="
Indent after split
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
#+END_SRC
OR (where necessary)
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
variableName =
longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+END_SRC
*not*
#+BEGIN_SRC C++
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
#+END_SRC
*nor*
#+BEGIN_SRC C++
variableName = longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
#+END_SRC
*** Maths and Logic
+ operator spacing
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
a + b, a - b
a*b, a/b
a & b, a ^ b
a = b, a != b
a < b, a > b, a >= b, a <= b
a || b, a && b
#+END_EXAMPLE
#+END_SRC
+ splitting formulae over several lines
Split and indent as per "splitting long lines at an ="
with the operator on the lower line. Align operator so that first
variable, function or bracket on the next line is 4 spaces indented i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
variableName =
a*(a + b)
*exp(c/d)
*(k + t);
#+END_EXAMPLE
#+END_SRC
This is sometimes more legible when surrounded by extra parentheses:
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
variableName =
(
a*(a + b)
*exp(c/d)
*(k + t)
);
#+END_EXAMPLE
#+END_SRC
+ splitting logical tests over several lines
outdent the operator so that the next variable to test is aligned with
the four space indentation, i.e.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
if
(
a == true
&& b == c
)
#+END_EXAMPLE
#+END_SRC
** Documentation
*** General
......@@ -331,7 +390,7 @@
description.
For example,
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
Class
Foam::myClass
......@@ -340,7 +399,7 @@
The class is implemented as a set of recommendations that may
sometimes be useful.
#+END_EXAMPLE
#+END_SRC
+ The class name must be qualified by its namespace, otherwise Doxygen
will think you are documenting some other class.
......@@ -348,33 +407,33 @@
+ If you don't have anything to say about the class (at the moment), use
the namespace-qualified class name for the description. This aids with
finding these under-documented classes later.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
Class
Foam::myUnderDocumentedClass
Description
Foam::myUnderDocumentedClass
#+END_EXAMPLE
#+END_SRC
+ Use 'Class' and 'Namespace' tags in the header files.
The Description block then applies to documenting the class.
+ Use 'InClass' and 'InNamespace' in the source files.
The Description block then applies to documenting the file itself.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
InClass
Foam::myClass
Description
Implements the read and writing of files.
#+END_EXAMPLE
#+END_SRC
*** Doxygen Special Commands
Doxygen has a large number of special commands with a =\= prefix.
Since the filtering removes the leading spaces within the blocks, the
Doxygen commmands can be inserted within the block without problems.
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
InClass
Foam::myClass
......@@ -398,7 +457,7 @@
... // some operation
}
\endcode
#+END_EXAMPLE
#+END_SRC
*** HTML Special Commands
Since Doxygen also handles HTML tags to a certain extent, the angle
......@@ -418,16 +477,16 @@
+ If the namespaces is used to hold sub-models, the namespace can be
documented in the same file as the class with the model selector.
eg,
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
#+END_EXAMPLE
#+END_SRC
+ If nothing else helps, find some sensible header.
eg,
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
namespace 'Foam' is documented in the foamVersion.H file
#+END_EXAMPLE
#+END_SRC
*** Documenting typedefs and classes defined via macros
... not yet properly resolved
......@@ -456,9 +515,9 @@
used as a variable or class method name, it is probably better to use
'-ize', which is considered the main form by the Oxford University
Press. Eg,
#+BEGIN_EXAMPLE
#+BEGIN_SRC C++
myClass.initialize()
#+END_EXAMPLE
#+END_SRC
The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
seems to confuse non-native (and some native) English speakers.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment