zhyang-dev/openfoam
1
0
Fork 0
mirror of https://develop.openfoam.com/Development/openfoam.git synced 2025-11-28 03:28:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation: converted javadoc @ to LaTeX style \ in Doxygen code docs

Browse Source
This commit is contained in:
Henry
2011-02-08 18:22:00 +00:00
parent 5339d687a4
commit c3cb632c24
221 changed files with 1096 additions and 8800 deletions
Download Patch File Download Diff File Expand all files Collapse all files

466
doc/codingStyleGuide.org
View File

@ -1,13 +1,14 @@
# -*- mode: org; -*-
#
#+TITLE: OpenFOAM C++ style guide
#+AUTHOR: OpenCFD Ltd.
#+DATE: June 2010
#+AUTHOR: 2011 OpenCFD Ltd.
#+DATE: Feb 2011
#+LINK: http://www.opencfd.co.uk
#+OPTIONS: author:nil ^:{}
#+STARTUP: hidestars
#+STARTUP: odd
* OpenFOAM C++ style guide
*** General
+ 80 character lines max
+ The normal indentation is 4 spaces per logical level.
@ -23,31 +24,24 @@
+ stream output
+ =<<= is always four characters after the start of the stream,
so that the =<<= symbols align, i.e.
#+BEGIN_EXAMPLE
Info<< ...
os << ...
#+END_EXAMPLE
so
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
#+BEGIN_EXAMPLE
Info<< ...
os << ...
#+END_EXAMPLE
so
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
WarningIn("className::functionName()")
<< "Warning message"
#+END_EXAMPLE
#+END_EXAMPLE
+ no unnecessary class section headers, i.e. remove
#+BEGIN_EXAMPLE
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
// Check
@ -55,117 +49,99 @@
// Write
#+END_EXAMPLE
if they contain nothing, even if planned for 'future use'
+ class titles are centred
#+BEGIN_EXAMPLE
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
/*---------------------------------------------------------------------------*\
/*---------------------------------------------------------------------------*\
Class exampleClass Declaration
\*---------------------------------------------------------------------------*/
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
*** 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
+ destructor
+ If adding a comment to the destructor -
use =//-= and code as a normal function:
#+BEGIN_EXAMPLE
//- Destructor
~className();
#+END_EXAMPLE
#+BEGIN_EXAMPLE
//- Destructor
~className();
#+END_EXAMPLE
+ inline functions
+ Use inline functions where appropriate in a separate /classNameI.H/ file.
Avoid cluttering the header file with function bodies.
+ Use inline functions where appropriate in a separate /classNameI.H/
file. Avoid cluttering the header file with function bodies.
*** The /.C/ Files
+ Do not open/close namespaces in a /.C/ file
+ Fully scope the function name, i.e.
#+BEGIN_EXAMPLE
Foam::returnType Foam::className::functionName()
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
namespace Foam
{
...
returnType className::functionName()
...
}
#+END_EXAMPLE
EXCEPTION
#+BEGIN_EXAMPLE
Foam::returnType Foam::className::functionName()
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
namespace Foam
{
...
returnType className::functionName()
...
}
#+END_EXAMPLE
EXCEPTION
When there are multiple levels of namespace, they may be used in the /.C/
file, i.e.
#+BEGIN_EXAMPLE
namespace Foam
{
namespace compressible
{
namespace RASModels
{
...
} // End namespace RASModels
} // End namespace compressible
} // End namespace Foam
#+END_EXAMPLE
When there are multiple levels of namespace, they may be used in the
/.C/ file, i.e.
#+BEGIN_EXAMPLE
namespace Foam
{
namespace compressible
{
namespace RASModels
{
...
} // End namespace RASModels
} // End namespace compressible
} // End namespace Foam
#+END_EXAMPLE
+ Use two empty lines between functions
*** Coding Practice
+ passing data as arguments or return values.
+ Pass bool, label and scalar as copy, anything larger by reference.
+ const
+ Use everywhere it is applicable.
+ variable initialisation using
#+BEGIN_EXAMPLE
const className& variableName = otherClass.data();
#+END_EXAMPLE
#+BEGIN_EXAMPLE
const className& variableName = otherClass.data();
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
const className& variableName(otherClass.data());
#+END_EXAMPLE
#+BEGIN_EXAMPLE
const className& variableName(otherClass.data());
#+END_EXAMPLE
+ virtual functions
+ If a class is virtual, make all derived classes virtual.
*** Conditional Statements
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
if (condition)
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
OR
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
if
(
long condition
@ -173,29 +149,24 @@
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
NOT (no space between =if= and =(= used)
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
if(condition)
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
*** =for= and =while= Loops
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
for (i = 0; i < maxI; i++)
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
OR
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
for
(
i = 0;
@ -205,33 +176,26 @@
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
NOT this (no space between =for= and =(= used)
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
for(i = 0; i < maxI; i++)
{
code;
}
#+END_EXAMPLE
#+END_EXAMPLE
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_EXAMPLE
forAll(
#+END_EXAMPLE
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
forAll (
#+END_EXAMPLE
#+END_EXAMPLE
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
@ -239,150 +203,120 @@
The following will FAIL!:
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
#+END_EXAMPLE
#+END_EXAMPLE
These convenience macros are also generally avoided in other
container classes and OpenFOAM primitive classes.
*** Splitting Over Multiple Lines
***** Splitting return type and function name
+ 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
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::
longFunctionName const
#+END_EXAMPLE
+ 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
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const
#+END_EXAMPLE
**** Splitting return type and function name
+ 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.
so
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::longClassName::longFunctionName const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
const
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName& Foam::longClassName::
longFunctionName const
#+END_EXAMPLE
+ if it needs to be split again, split at the function name (leaving
behind the preceding scoping =::=s), and again, left align, i.e.
For example,
#+BEGIN_EXAMPLE
const Foam::longReturnTypeName&
Foam::veryveryveryverylongClassName::
veryveryveryverylongFunctionName const
#+END_EXAMPLE
**** Splitting long lines at an "="
***** Splitting long lines at an "="
Indent after split
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
#+END_EXAMPLE
OR (where necessary)
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
#+END_EXAMPLE
NOT
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
variableName =
longClassName.longFunctionName(longArgument);
#+END_EXAMPLE
#+END_EXAMPLE
NOR
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
variableName = longClassName.longFunctionName
(
longArgument1,
longArgument2
);
#+END_EXAMPLE
#+END_EXAMPLE
*** Maths and Logic
+ operator spacing
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
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_EXAMPLE
+ 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
variableName =
a * (a + b)
- exp(c/d)
* (k + t);
#+END_EXAMPLE
#+BEGIN_EXAMPLE
variableName =
a*(a + b)
*exp(c/d)
*(k + t);
#+END_EXAMPLE
This is sometimes more legible when surrounded by extra parentheses:
#+BEGIN_EXAMPLE
variableName =
(
a * (a + b)
- exp(c/d)
* (k + t)
);
#+END_EXAMPLE
#+BEGIN_EXAMPLE
variableName =
(
a*(a + b)
*exp(c/d)
*(k + t)
);
#+END_EXAMPLE
+ 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
if
(
a == true
&& b == c
)
#+END_EXAMPLE
#+BEGIN_EXAMPLE
if
(
a == true
&& b == c
)
#+END_EXAMPLE
** Documentation
*** General
+ For readability in the comment blocks, certain tags are used that are
translated by pre-filtering the file before sending it to Doxygen.
@ -397,17 +331,16 @@
description.
For example,
#+BEGIN_EXAMPLE
Class
Foam::myClass
#+BEGIN_EXAMPLE
Class
Foam::myClass
Description
A class for specifying the documentation style.
Description
A class for specifying the documentation style.
The class is implemented as a set of recommendations that may
sometimes be useful.
#+END_EXAMPLE
The class is implemented as a set of recommendations that may
sometimes be useful.
#+END_EXAMPLE
+ The class name must be qualified by its namespace, otherwise Doxygen
will think you are documenting some other class.
@ -415,49 +348,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
Class
Foam::myUnderDocumentedClass
#+BEGIN_EXAMPLE
Class
Foam::myUnderDocumentedClass
Description
Foam::myUnderDocumentedClass
#+END_EXAMPLE
Description
Foam::myUnderDocumentedClass
#+END_EXAMPLE
+ 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
InClass
Foam::myClass
#+BEGIN_EXAMPLE
InClass
Foam::myClass
Description
Implements the read and writing of files.
#+END_EXAMPLE
Description
Implements the read and writing of files.
#+END_EXAMPLE
*** Doxygen Special Commands
Doxygen has a large number of special commands with a =\= prefix.
Doxygen has a large number of special commands with a =\= prefix or
(alternatively) an =@= prefix.
The =@= prefix form is recommended for most Doxygen specials, since it
has the advantage of standing out. It also happens to be what projects
like gcc and VTK are using.
The =\= prefix form, however, looks a bit better for the =\n= newline
command and when escaping single characters - eg, =\@=, =\<=, =\>=, etc.
Since the filtering removes the leading 4 spaces within the blocks, the
Since the filtering removes the leading spaces within the blocks, the
Doxygen commmands can be inserted within the block without problems.
#+BEGIN_EXAMPLE
#+BEGIN_EXAMPLE
InClass
Foam::myClass
@ -465,68 +382,57 @@
Implements the read and writing of files.
An example input file:
@verbatim
\verbatim
patchName
{
type myPatchType;
refValue 100;
value uniform 1;
}
@endverbatim
\endverbatim
Within the implementation, a loop over all patches is done:
@code
\code
forAll(patches, patchI)
{
... // some operation
}
@endcode
#+END_EXAMPLE
\endcode
#+END_EXAMPLE
*** HTML Special Commands
Since Doxygen also handles HTML tags to a certain extent, the angle
brackets need quoting in the documentation blocks. Non-HTML tags cause
Doxygen to complain, but seem to work anyhow.
eg,
+ The template with type =<HR>= is a bad example.
+ The template with type =\<HR\>= is a better example.
+ The template with type =<Type>= causes Doxygen to complain about an
unknown html type, but it seems to work okay anyhow.
*** Documenting Namespaces
+ If namespaces are explictly declared with the =Namespace()= macro,
they should be documented there.
+ 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
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
#+END_EXAMPLE
#+BEGIN_EXAMPLE
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
#+END_EXAMPLE
+ If nothing else helps, find some sensible header.
eg,
#+BEGIN_EXAMPLE
namespace 'Foam' is documented in the foamVersion.H file
#+END_EXAMPLE
#+BEGIN_EXAMPLE
namespace 'Foam' is documented in the foamVersion.H file
#+END_EXAMPLE
*** Documenting typedefs and classes defined via macros
... not yet properly resolved
*** Documenting Applications
Any number of classes might be defined by a particular application, but
these classes will not, however, be available to other parts of
OpenFOAM. At the moment, the sole purpuse for running Doxygen on the
@ -542,23 +448,17 @@
The layout of the application documentation has not yet been finalized,
but foamToVTK shows an initial attempt.
*** Orthography (an opinion)
Given the origins of OpenFOAM, the British spellings (eg, neighbour and
not neighbor) are generally favoured. For code sections that interact
with external libraries, it can be useful to adopt American spellings,
especially for names that constitute a significant part of the external
library - eg, 'color' within graphics sub-systems.
*** Orthography
Given the origins of OpenFOAM, the British spellings (eg, neighbour and not
neighbor) are generally favoured.
Both '-ize' and the '-ise' variant are found in the code comments. If
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
Press. Eg,
#+BEGIN_EXAMPLE
myClass.initialize()
#+END_EXAMPLE
#+END_EXAMPLE
The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
seems to confuse non-native (and some native) English speakers.

BIN
doc/codingStyleGuide.pdf
View File

Binary file not shown.

16
doc/doxygen/Doxyfile
View File

@ -581,16 +581,16 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
#INPUT = $(WM_PROJECT_DIR)/src \
# $(WM_PROJECT_DIR)/applications/utilities \
# $(WM_PROJECT_DIR)/applications/solvers
INPUT = $(WM_PROJECT_DIR)/src \
$(WM_PROJECT_DIR)/applications/utilities \
$(WM_PROJECT_DIR)/applications/solvers
# limit input for testing purposes
INPUT = $(WM_PROJECT_DIR)/src/OpenFOAM/global \
$(WM_PROJECT_DIR)/src/OpenFOAM/containers \
$(WM_PROJECT_DIR)/src/OpenFOAM/primitives \
$(WM_PROJECT_DIR)/sampling \
$(WM_PROJECT_DIR)/src/finiteVolume/fvMesh
# INPUT = $(WM_PROJECT_DIR)/src/OpenFOAM/global \
# $(WM_PROJECT_DIR)/src/OpenFOAM/containers \
# $(WM_PROJECT_DIR)/src/OpenFOAM/primitives \
# $(WM_PROJECT_DIR)/sampling \
# $(WM_PROJECT_DIR)/src/finiteVolume/fvMesh
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is