diff --git a/doc/GUIDELINES b/doc/GUIDELINES
index 8038f997de186017c4b2fe1519fc8aa471a0bd0c..5603ca3f657c13001b1e584452c3592d0be93360 100644
--- a/doc/GUIDELINES
+++ b/doc/GUIDELINES
@@ -109,7 +109,7 @@ eg,
|
| Within the implementation, a loop over all patches is done:
| @code
- | forAll (patches, patchI)
+ | forAll(patches, patchI)
| {
| ... // some operation
| }
@@ -222,4 +222,4 @@ The doc/Doxygen/tools directory contains miscellaneous scripts for finding
and possibly repairing documentation issues.
-Updated: 2008-03-17
+Updated: 2009-11-27
diff --git a/doc/codingStyleGuide.org b/doc/codingStyleGuide.org
index 6c5f691aa54955b9154246c70acae9d41ae1445b..da50ffcd93a5ce855af1f393a03cb4597957a6fa 100644
--- a/doc/codingStyleGuide.org
+++ b/doc/codingStyleGuide.org
@@ -17,292 +17,244 @@
+ Avoid trailing whitespace.
+ stream output
- << is always four characters after the start of the stream,
- so that the << symbols align, i.e.
+ =<<= is always four characters after the start of the stream,
+ so that the =<<= symbols align, i.e.
-#+BEGIN_EXAMPLE
- Info<< ...
- os << ...
-#+END_EXAMPLE
+ :Info<< ...
+ :os << ...
so
-#+BEGIN_EXAMPLE
- WarningIn("className::functionName()")
- << "Warning message"
-#+END_EXAMPLE
+ :WarningIn("className::functionName()")
+ : << "Warning message"
NOT
-#+BEGIN_EXAMPLE
- WarningIn("className::functionName()")
- << "Warning message"
-#+END_EXAMPLE
+ :WarningIn("className::functionName()")
+ :<< "Warning message"
- + no unnecessary class section headers, i.e. remove
-
-#+BEGIN_EXAMPLE
- // * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
-
- // Check
- // Edit
+ + no unnecessary class section headers, i.e. remove
- // Write
-#+END_EXAMPLE
+ :// * * * * * * * * * * * * * Private Member Functions * * * * * * * * * * * //
+ :
+ :// Check
+ :
+ :// Edit
+ :
+ :// Write
if they contain nothing, even if planned for 'future use'
+ class titles are centred
-#+BEGIN_EXAMPLE
- /*---------------------------------------------------------------------------*\
- Class exampleClass Declaration
- \*---------------------------------------------------------------------------*/
-#+END_EXAMPLE
+ :/*---------------------------------------------------------------------------*\
+ : Class exampleClass Declaration
+ :\*---------------------------------------------------------------------------*/
- NOT
+ NOT
-#+BEGIN_EXAMPLE
- /*---------------------------------------------------------------------------*\
- Class exampleClass Declaration
- \*---------------------------------------------------------------------------*/
-#+END_EXAMPLE
+ :/*---------------------------------------------------------------------------*\
+ : Class exampleClass Declaration
+ :\*---------------------------------------------------------------------------*/
-*** .H Files
+*** The =.H= Files
+ header file spacing
- Leave two empty lines between sections (as per functions in the .C file etc)
+ 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
+ ://- Destructor
+ :~className();
+
+ inline functions
Use inline functions where appropriate in a separate classNameI.H file.
Avoid cluttering the header file with function bodies.
-*** .C Files
- + Do not open/close namespaces in a .C file
+*** 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
+ :Foam::returnType Foam::className::functionName()
NOT
-#+BEGIN_EXAMPLE
- namespace Foam
- {
- ...
-
- returnType className::functionName()
-
- ...
- }
-#+END_EXAMPLE
+ :namespace Foam
+ :{
+ : ...
+ :
+ : returnType className::functionName()
+ :
+ : ...
+ :}
EXCEPTION
- When there are multiple levels of namespace, they may be used in the .C
+ 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
+ :namespace Foam
+ :{
+ :namespace compressible
+ :{
+ :namespace RASModels
+ :{
+ :
+ : ...
+ :
+ :} // End namespace RASModels
+ :} // End namespace compressible
+ :} // End namespace Foam
+ Use two empty lines between functions
-*** Coding Practise
+*** Coding Practice
+ passing data as arguments or return
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
+ : const className& variableName = otherClass.data();
NOT
-#+BEGIN_EXAMPLE
- const className& variableName(otherClass.data());
-#+END_EXAMPLE
+ : const className& variableName(otherClass.data());
+ virtual functions
If a class is virtual - make all derived classes virtual.
*** Conditional Statements
-#+BEGIN_EXAMPLE
- if (condition)
- {
- code;
- }
-#+END_EXAMPLE
+ :if (condition)
+ :{
+ : code;
+ :}
OR
-#+BEGIN_EXAMPLE
- if
- (
- long condition
- )
- {
- code;
- }
-#+END_EXAMPLE
+ :if
+ :(
+ : long condition
+ :)
+ :{
+ : code;
+ :}
NOT (no space between "if" and "(")
-#+BEGIN_EXAMPLE
- if(condition)
- {
- code;
- }
-#+END_EXAMPLE
-
-*** `for' Loops
-#+BEGIN_EXAMPLE
- for (i = 0; i < maxI; i++)
- {
- code;
- }
-#+END_EXAMPLE
+ :if(condition)
+ :{
+ : code;
+ :}
+
+*** =for= Loops
+ :for (i = 0; i < maxI; i++)
+ :{
+ : code;
+ :}
OR
-#+BEGIN_EXAMPLE
- for
- (
- i = 0;
- i < maxI;
- i++
- )
- {
- code;
- }
-#+END_EXAMPLE
+ :for
+ :(
+ : i = 0;
+ : i < maxI;
+ : i++
+ :)
+ :{
+ : code;
+ :}
NOT (no space between "for" and "(")
-#+BEGIN_EXAMPLE
- for(i = 0; i < maxI; i++)
- {
- code;
- }
-#+END_EXAMPLE
+ :for(i = 0; i < maxI; i++)
+ :{
+ : code;
+ :}
+
+ Note that when indexing through iterators, it is often slightly more
+ efficient to use the pre-increment form. Eg, =++iter= instead of =iter++=
-*** `forAll' loops
- like for loops, but
+*** =forAll= loops
+ like =for= loops, but
-#+BEGIN_EXAMPLE
- forAll(
-#+END_EXAMPLE
+ :forAll(
NOT
-#+BEGIN_EXAMPLE
- forAll (
-#+END_EXAMPLE
+ :forAll (
*** Splitting Over Multiple Lines
- + splitting return type and function name
+
+**** 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.
+ + 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
+ :const Foam::longReturnTypeName&
+ :Foam::longClassName::longFunctionName const
NOT
-#+BEGIN_EXAMPLE
- const Foam::longReturnTypeName&
- Foam::longClassName::longFunctionName const
-#+END_EXAMPLE
+ :const Foam::longReturnTypeName&
+ : Foam::longClassName::longFunctionName const
NOR
-#+BEGIN_EXAMPLE
- const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
- const
-#+END_EXAMPLE
+ :const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
+ :const
NOR
-#+BEGIN_EXAMPLE
- const Foam::longReturnTypeName& Foam::longClassName::
- longFunctionName const
-#+END_EXAMPLE
+ :const Foam::longReturnTypeName& Foam::longClassName::
+ :longFunctionName const
+
+ + if it needs to be split again, split at the function name (leaving
+ behind the preceding scoping "::"s), and again, left align, i.e.
- + if need to 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
+ :const Foam::longReturnTypeName&
+ :Foam::veryveryveryverylongClassName::
+ :veryveryveryverylongFunctionName const
- + splitting long lines at an "="
+**** Splitting long lines at an "="
Indent after split
-#+BEGIN_EXAMPLE
- variableName =
- longClassName.longFunctionName(longArgument);
-#+END_EXAMPLE
+ :variableName =
+ : longClassName.longFunctionName(longArgument);
OR (where necessary)
-#+BEGIN_EXAMPLE
- variableName =
- longClassName.longFunctionName
- (
- longArgument1,
- longArgument2
- );
-#+END_EXAMPLE
+ :variableName =
+ : longClassName.longFunctionName
+ : (
+ : longArgument1,
+ : longArgument2
+ : );
NOT
-#+BEGIN_EXAMPLE
- variableName =
- longClassName.longFunctionName(longArgument);
-#+END_EXAMPLE
+ :variableName =
+ :longClassName.longFunctionName(longArgument);
NOR
-#+BEGIN_EXAMPLE
- variableName = longClassName.longFunctionName
- (
- longArgument1,
- longArgument2
- );
-#+END_EXAMPLE
+ :variableName = longClassName.longFunctionName
+ :(
+ : longArgument1,
+ : longArgument2
+ :);
*** Maths and Logic
+ operator spacing
@@ -318,34 +270,201 @@
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
+ :variableName =
+ : a * (a + b)
+ : - exp(c/d)
+ : * (k + t);
This is sometime more legible when surrounded by extra parentheses:
-#+BEGIN_EXAMPLE
- variableName =
- (
- a * (a + b)
- - exp(c/d)
- * (k + t)
- );
-#+END_EXAMPLE
+ :variableName =
+ :(
+ : a * (a + b)
+ : - exp(c/d)
+ : * (k + t)
+ :);
+ 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
+ :if
+ :(
+ : a == true
+ : && b == c
+ :)
+
+** 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.
+
+ + The tags start in column 1, the contents follow on the next lines and
+ indented by 4 spaces. The filter removes the leading 4 spaces from the
+ following lines until the next tag that starts in column 1.
+
+ + The 'Class' and 'Description' tags are the most important ones.
+
+ + The first paragraph following the 'Description' will be used for the
+ brief description, the remaining paragraphs become the detailed
+ description.
+
+ For example,
+
+ :Class
+ : Foam::myClass
+ :
+ :Description
+ : A class for specifying the documentation style.
+ :
+ : The class is implemented as a set of recommendations that may
+ : sometimes be useful.
+
+ + The class name must be qualified by its namespace, otherwise Doxygen
+ will think you are documenting some other class.
+
+ + 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.
+
+
+ :Class
+ : Foam::myUnderDocumentedClass
+ :
+ :Description
+ : Foam::myUnderDocumentedClass
+
+
+ + 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.
+
+
+ :InClass
+ : Foam::myClass
+ :
+ :Description
+ : Implements the read and writing of files.
+
+*** Doxygen Special Commands
+
+ Doxygen has a large number of special commands with a '\' prefix or a
+ (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
+ Doxygen commmands can be inserted within the block without problems.
+
+
+ :InClass
+ : Foam::myClass
+ :
+ :Description
+ : Implements the read and writing of files.
+ :
+ : An example input file:
+ : @verbatim
+ : patchName
+ : {
+ : type myPatchType;
+ : refValue 100;
+ : value uniform 1;
+ : }
+ : @endverbatim
+ :
+ : Within the implementation, a loop over all patches is done:
+ : @code
+ : forAll(patches, patchI)
+ : {
+ : ... // some operation
+ : }
+ : @endcode
+
+*** 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,
+ :documented namespace 'Foam::functionEntries' within the
+ :class 'Foam::functionEntry'
+
+ + If nothing else helps, find some sensible header.
+ eg,
+ :namespace 'Foam' is documented in the foamVersion.H file
+
+
+*** 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
+ applications is to extract program usage information for the '-doc'
+ option.
+
+ The documentation for a particular application is normally contained
+ within the first comment block in a =.C= source file. The solution is this
+ to invoke a special filter for the "applications/{solver,utilities}"
+ directories that only allows the initial comment block for the =.C= files
+ through.
+
+ 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.
+
+ 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,
+ :myClass.initialize()
+
+
+ The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
+ seems to confuse non-native (and some native) English speakers.
+ It is better to donate the extra keystrokes and write "it is" or "it has".
+ Any remaining "it's" are likely an incorrect spelling of "its".
+
+