STYLE: use #+BEGIN_EXAMPLE / #+END_EXAMPLE in codingStyleGuide.org

- seems to work more reliably than the previous indented colons

doc/codingStyleGuide.org

@@ -18,97 +18,116 @@
       made with 'break' or 'continue' as part of a control structure.
 
     + 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.
 
-    :Info<< ...
-    :os  << ...
+#+BEGIN_EXAMPLE
+    Info<< ...
+    os  << ...
+#+END_EXAMPLE
 
       so
 
-    :WarningIn("className::functionName()")
-    :    << "Warning message"
+#+BEGIN_EXAMPLE
+    WarningIn("className::functionName()")
+        << "Warning message"
+#+END_EXAMPLE
 
       NOT
 
-    :WarningIn("className::functionName()")
-    :<< "Warning message"
+#+BEGIN_EXAMPLE
+    WarningIn("className::functionName()")
+    << "Warning message"
+#+END_EXAMPLE
 
 
     + no unnecessary class section headers, i.e. remove
 
-    :// * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
-    :
-    :// Check
-    :
-    :// Edit
-    :
-    :// Write
+#+BEGIN_EXAMPLE
+    // * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
+
+    // Check
+
+    // Edit
+
+    // Write
+#+END_EXAMPLE
+
 
       if they contain nothing, even if planned for 'future use'
 
     + class titles are centred
 
-    :/*---------------------------------------------------------------------------*\
-    :                        Class exampleClass Declaration
-    :\*---------------------------------------------------------------------------*/
+#+BEGIN_EXAMPLE
+    /*---------------------------------------------------------------------------*\
+                            Class exampleClass Declaration
+    \*---------------------------------------------------------------------------*/
+#+END_EXAMPLE
 
       NOT
 
-    :/*---------------------------------------------------------------------------*\
-    :               Class exampleClass Declaration
-    :\*---------------------------------------------------------------------------*/
+#+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)
+      + 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:
+      + If adding a comment to the destructor -
+        use //- and code as a normal function:
 
-    ://- Destructor
-    :~className();
+#+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.
+      + Fully scope the function name, i.e.
 
-    :Foam::returnType Foam::className::functionName()
+#+BEGIN_EXAMPLE
+    Foam::returnType Foam::className::functionName()
+#+END_EXAMPLE
 
       NOT
 
-    :namespace Foam
-    :{
-    :    ...
-    :
-    :    returnType className::functionName()
-    :
-    :    ...
-    :}
+#+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.
 
-    :namespace Foam
-    :{
-    :namespace compressible
-    :{
-    :namespace RASModels
-    :{
-    :
-    :    ...
-    :
-    :} // End namespace RASModels
-    :} // End namespace compressible
-    :} // End namespace Foam
+#+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
 
@@ -131,64 +150,95 @@
       If a class is virtual - make all derived classes virtual.
 
 *** Conditional Statements
-    :if (condition)
-    :{
-    :    code;
-    :}
+#+BEGIN_EXAMPLE
+    if (condition)
+    {
+        code;
+    }
+#+END_EXAMPLE
 
     OR
 
-    :if
-    :(
-    :   long condition
-    :)
-    :{
-    :    code;
-    :}
+#+BEGIN_EXAMPLE
+    if
+    (
+       long condition
+    )
+    {
+        code;
+    }
+#+END_EXAMPLE
 
     NOT (no space between "if" and "(")
 
-    :if(condition)
-    :{
-    :    code;
-    :}
+#+BEGIN_EXAMPLE
+    if(condition)
+    {
+        code;
+    }
+#+END_EXAMPLE
 
 *** =for= and =while= Loops
-    :for (i = 0; i < maxI; i++)
-    :{
-    :    code;
-    :}
+
+#+BEGIN_EXAMPLE
+    for (i = 0; i < maxI; i++)
+    {
+        code;
+    }
+#+END_EXAMPLE
 
     OR
 
-    :for
-    :(
-    :    i = 0;
-    :    i < maxI;
-    :    i++
-    :)
-    :{
-    :    code;
-    :}
+#+BEGIN_EXAMPLE
+    for
+    (
+        i = 0;
+        i < maxI;
+        i++
+    )
+    {
+        code;
+    }
+#+END_EXAMPLE
 
     NOT (no space between "for" and "(")
 
-    :for(i = 0; i < maxI; i++)
-    :{
-    :    code;
-    :}
+#+BEGIN_EXAMPLE
+    for(i = 0; i < maxI; i++)
+    {
+        code;
+    }
+#+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=, etc. loops
+*** =forAll=, =forAllIter=, =forAllConstIter=, etc. loops
     like =for= loops, but
 
-    :forAll(
+#+BEGIN_EXAMPLE
+    forAll(
+#+END_EXAMPLE
 
     NOT
 
-    :forAll (
+#+BEGIN_EXAMPLE
+    forAll (
+#+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
+    any commas.
+
+    The following will FAIL!:
+
+#+BEGIN_EXAMPLE
+    forAllIter(HashTable<labelPair, edge, Hash<edge> >, foo, iter)
+#+END_EXAMPLE
+
+    These convenience macros are also generally avoided in other
+    container classes and OpenFOAM primitive classes.
 
 *** Splitting Over Multiple Lines
 
@@ -198,64 +248,81 @@
      + do not put "const" onto its own line - use a split to keep it with
        the function name and arguments.
 
-     so:
+     so
 
-     :const Foam::longReturnTypeName&
-     :Foam::longClassName::longFunctionName const
+#+BEGIN_EXAMPLE
+     const Foam::longReturnTypeName&
+     Foam::longClassName::longFunctionName const
+#+END_EXAMPLE
 
      NOT
 
-     :const Foam::longReturnTypeName&
-     :    Foam::longClassName::longFunctionName const
+#+BEGIN_EXAMPLE
+     const Foam::longReturnTypeName&
+         Foam::longClassName::longFunctionName const
+#+END_EXAMPLE
 
      NOR
 
-     :const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
-     :const
+#+BEGIN_EXAMPLE
+     const Foam::longReturnTypeName& Foam::longClassName::longFunctionName
+     const
+#+END_EXAMPLE
 
      NOR
 
-     :const Foam::longReturnTypeName& Foam::longClassName::
-     :longFunctionName const
-
+#+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,
 
-     :const Foam::longReturnTypeName&
-     :Foam::veryveryveryverylongClassName::
-     :veryveryveryverylongFunctionName const
+#+BEGIN_EXAMPLE
+     const Foam::longReturnTypeName&
+     Foam::veryveryveryverylongClassName::
+     veryveryveryverylongFunctionName const
+#+END_EXAMPLE
 
 **** Splitting long lines at an "="
 
      Indent after split
 
-     :variableName =
-     :    longClassName.longFunctionName(longArgument);
+#+BEGIN_EXAMPLE
+     variableName =
+         longClassName.longFunctionName(longArgument);
+#+END_EXAMPLE
 
      OR (where necessary)
 
-     :variableName =
-     :    longClassName.longFunctionName
-     :    (
-     :        longArgument1,
-     :        longArgument2
-     :    );
+#+BEGIN_EXAMPLE
+     variableName =
+         longClassName.longFunctionName
+         (
+             longArgument1,
+             longArgument2
+         );
+#+END_EXAMPLE
 
      NOT
 
-     :variableName =
-     :longClassName.longFunctionName(longArgument);
+#+BEGIN_EXAMPLE
+     variableName =
+     longClassName.longFunctionName(longArgument);
+#+END_EXAMPLE
 
      NOR
 
-     :variableName = longClassName.longFunctionName
-     :(
-     :    longArgument1,
-     :    longArgument2
-     :);
+#+BEGIN_EXAMPLE
+     variableName = longClassName.longFunctionName
+     (
+         longArgument1,
+         longArgument2
+     );
+#+END_EXAMPLE
 
 *** Maths and Logic
     + operator spacing
@@ -267,34 +334,41 @@
       + a || b, a && b
 
     + 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.
 
-    :variableName =
-    :    a * (a + b)
-    :  - exp(c/d)
-    :  * (k + t);
+#+BEGIN_EXAMPLE
+    variableName =
+        a * (a + b)
+      - exp(c/d)
+      * (k + t);
+#+END_EXAMPLE
 
       This is sometime more legible when surrounded by extra parentheses:
 
-    :variableName =
-    :(
-    :    a * (a + b)
-    :  - exp(c/d)
-    :  * (k + t)
-    :);
+#+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.
 
-    :if
-    :(
-    :    a == true
-    : && b == c
-    :)
+#+BEGIN_EXAMPLE
+    if
+    (
+        a == true
+     && b == c
+    )
+#+END_EXAMPLE
 
 ** Documentation
 
@@ -315,14 +389,16 @@
 
       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.
+#+BEGIN_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.
+#+END_EXAMPLE
 
     + The class name must be qualified by its namespace, otherwise Doxygen
       will think you are documenting some other class.
@@ -332,11 +408,13 @@
       finding these under-documented classes later.
 
 
-    :Class
-    :    Foam::myUnderDocumentedClass
-    :
-    :Description
-    :    Foam::myUnderDocumentedClass
+#+BEGIN_EXAMPLE
+    Class
+        Foam::myUnderDocumentedClass
+
+    Description
+        Foam::myUnderDocumentedClass
+#+END_EXAMPLE
 
 
     + Use 'Class' and 'Namespace' tags in the header files.
@@ -346,11 +424,13 @@
       The Description block then applies to documenting the file itself.
 
 
-    :InClass
-    :    Foam::myClass
-    :
-    :Description
-    :    Implements the read and writing of files.
+#+BEGIN_EXAMPLE
+    InClass
+        Foam::myClass
+
+    Description
+        Implements the read and writing of files.
+#+END_EXAMPLE
 
 *** Doxygen Special Commands
 
@@ -368,29 +448,31 @@
     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
+#+BEGIN_EXAMPLE
+    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
+#+END_EXAMPLE
 
 *** HTML Special Commands
 
@@ -399,28 +481,34 @@
     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 bad example.
 
-    + The template with type \<HR\> is a better example.
+    + The template with type =\<HR\>= is a better example.
 
-    + The template with type <Type> causes Doxygen to complain about an
+    + 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,
+    + 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'
+
+#+BEGIN_EXAMPLE
+    documented namespace 'Foam::functionEntries' within the
+    class 'Foam::functionEntry'
+#+END_EXAMPLE
 
     + If nothing else helps, find some sensible header.
       eg,
-    :namespace 'Foam' is documented in the foamVersion.H file
+
+#+BEGIN_EXAMPLE
+    namespace 'Foam' is documented in the foamVersion.H file
+#+END_EXAMPLE
 
 
 *** Documenting Typedefs and classes defined via macros
@@ -459,7 +547,9 @@
     Press.
 
     Eg,
-    :myClass.initialize()
+#+BEGIN_EXAMPLE
+    myClass.initialize()
+#+END_EXAMPLE
 
 
     The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
@@ -468,4 +558,3 @@
     Any remaining "it's" are likely an incorrect spelling of "its".
 
 
-