From abeef3313d169f7ffe8f9540308673f479634f5c Mon Sep 17 00:00:00 2001
From: Andrew Heather <a.heather@opencfd.co.uk>
Date: Wed, 9 Dec 2015 16:10:35 +0000
Subject: [PATCH] STYLE: Updated header file documentation

---
 .../solvers/combustion/chemFoam/chemFoam.C      |  7 ++++---
 .../chtMultiRegionFoam/chtMultiRegionFoam.C     |  9 +++++----
 .../incompressible/boundaryFoam/boundaryFoam.C  |  2 +-
 .../coalChemistryFoam/coalChemistryFoam.C       | 13 ++++++-------
 .../reactingParcelFoam/reactingParcelFoam.C     |  7 +++++--
 .../steadyParticleTracks/steadyParticleTracks.C |  4 +++-
 .../faceAgglomerate/faceAgglomerate.C           |  1 -
 .../preProcessing/mapFields/mapFields.C         |  1 +
 .../surfaceBooleanFeatures.C                    | 17 ++++++++---------
 .../surface/surfaceClean/surfaceClean.C         |  3 +++
 .../surface/surfaceCoarsen/surfaceCoarsen.C     |  5 ++++-
 .../surface/surfaceInertia/surfaceInertia.C     |  5 +++--
 .../surfaceRefineRedGreen.C                     |  8 +++++++-
 .../surfaceSplitByTopology.C                    |  6 +++---
 14 files changed, 53 insertions(+), 35 deletions(-)

diff --git a/applications/solvers/combustion/chemFoam/chemFoam.C b/applications/solvers/combustion/chemFoam/chemFoam.C
index cc94807a394..b4e5df68d04 100644
--- a/applications/solvers/combustion/chemFoam/chemFoam.C
+++ b/applications/solvers/combustion/chemFoam/chemFoam.C
@@ -28,9 +28,10 @@ Group
     grpCombustionSolvers
 
 Description
-    Solver for chemistry problems
-    - designed for use on single cell cases to provide comparison against
-      other chemistry solvers
+    Solver for chemistry problems designed for use on single cell cases to
+    provide comparison against other chemistry solvers
+
+    Note:
     - single cell mesh created on-the-fly
     - fields created on the fly from the initial conditions
 
diff --git a/applications/solvers/heatTransfer/chtMultiRegionFoam/chtMultiRegionFoam.C b/applications/solvers/heatTransfer/chtMultiRegionFoam/chtMultiRegionFoam.C
index f00fb7fa05d..eca1109a4cd 100644
--- a/applications/solvers/heatTransfer/chtMultiRegionFoam/chtMultiRegionFoam.C
+++ b/applications/solvers/heatTransfer/chtMultiRegionFoam/chtMultiRegionFoam.C
@@ -29,11 +29,12 @@ Group
 
 Description
     Combination of heatConductionFoam and buoyantFoam for conjugate heat
-    transfer between solid regions and fluid regions. Both regions include
-    the fvOptions framework.
+    transfer between solid regions and fluid regions.
 
-    It handles secondary fluid or solid circuits which can be coupled
-    thermally with the main fluid region. i.e radiators, etc.
+    Note:
+    - Both regions support the fvOptions framework.
+    - It handles secondary fluid or solid circuits which can be coupled
+      thermally with the main fluid region. i.e radiators, etc.
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/solvers/incompressible/boundaryFoam/boundaryFoam.C b/applications/solvers/incompressible/boundaryFoam/boundaryFoam.C
index dc707b61dd1..4a35ff7a487 100644
--- a/applications/solvers/incompressible/boundaryFoam/boundaryFoam.C
+++ b/applications/solvers/incompressible/boundaryFoam/boundaryFoam.C
@@ -29,7 +29,7 @@ Group
 
 Description
     Steady-state solver for incompressible, 1D turbulent flow, typically to
-    generate boundary layer conditions at an inlet, for use in a simulation.
+    generate boundary layer conditions at an inlet.
 
     Boundary layer code to calculate the U, k and epsilon distributions.
     Used to create inlet boundary conditions for experimental comparisons
diff --git a/applications/solvers/lagrangian/coalChemistryFoam/coalChemistryFoam.C b/applications/solvers/lagrangian/coalChemistryFoam/coalChemistryFoam.C
index ab799c64965..7d4839d56b0 100644
--- a/applications/solvers/lagrangian/coalChemistryFoam/coalChemistryFoam.C
+++ b/applications/solvers/lagrangian/coalChemistryFoam/coalChemistryFoam.C
@@ -28,13 +28,12 @@ Group
     grpLagrangianSolvers
 
 Description
-    Transient solver for:
-    - compressible,
-    - turbulent flow,
-    with
-    - coal and limestone parcel injections,
-    - energy source, and
-    - combustion.
+    Transient PIMPLE solver for compressible, laminar or turbulent flow with 
+    coal and thermodynamic parcels, and combustion.
+
+    Note:
+    - includes run-time selectable finite volume options, e.g. sources,
+      constraints
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/solvers/lagrangian/reactingParcelFoam/reactingParcelFoam.C b/applications/solvers/lagrangian/reactingParcelFoam/reactingParcelFoam.C
index 38f205d3206..3bf98dd969a 100644
--- a/applications/solvers/lagrangian/reactingParcelFoam/reactingParcelFoam.C
+++ b/applications/solvers/lagrangian/reactingParcelFoam/reactingParcelFoam.C
@@ -29,8 +29,11 @@ Group
 
 Description
     Transient PIMPLE solver for compressible, laminar or turbulent flow with
-    reacting multiphase Lagrangian parcels, including run-time selectable
-    finite volume options, e.g. sources, constraints
+    reacting multiphase Lagrangian parcels.
+
+    Note:
+    - includes run-time selectable finite volume options, e.g. sources,
+      constraints
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/utilities/postProcessing/lagrangian/steadyParticleTracks/steadyParticleTracks.C b/applications/utilities/postProcessing/lagrangian/steadyParticleTracks/steadyParticleTracks.C
index 2941df5d5a0..0f279d33587 100644
--- a/applications/utilities/postProcessing/lagrangian/steadyParticleTracks/steadyParticleTracks.C
+++ b/applications/utilities/postProcessing/lagrangian/steadyParticleTracks/steadyParticleTracks.C
@@ -27,7 +27,9 @@ Application
 Description
     Generates a VTK file of particle tracks for cases that were computed using
     a steady-state cloud
-    NOTE: case must be re-constructed (if running in parallel) before use
+
+    Note:
+    - Case must be re-constructed (if running in parallel) before use
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/utilities/preProcessing/faceAgglomerate/faceAgglomerate.C b/applications/utilities/preProcessing/faceAgglomerate/faceAgglomerate.C
index be2310aabe7..9da11895bf5 100644
--- a/applications/utilities/preProcessing/faceAgglomerate/faceAgglomerate.C
+++ b/applications/utilities/preProcessing/faceAgglomerate/faceAgglomerate.C
@@ -25,7 +25,6 @@ Application
     faceAgglomerate
 
 Description
-
     Agglomerate boundary faces using the pairPatchAgglomeration algorithm.
     It writes a map from the fine to coarse grid.
 
diff --git a/applications/utilities/preProcessing/mapFields/mapFields.C b/applications/utilities/preProcessing/mapFields/mapFields.C
index 6f72053a08a..0e381e48915 100644
--- a/applications/utilities/preProcessing/mapFields/mapFields.C
+++ b/applications/utilities/preProcessing/mapFields/mapFields.C
@@ -27,6 +27,7 @@ Application
 Description
     Maps volume fields from one mesh to another, reading and
     interpolating all fields present in the time directory of both cases.
+
     Parallel and non-parallel cases are handled without the need to reconstruct
     them first.
 
diff --git a/applications/utilities/surface/surfaceBooleanFeatures/surfaceBooleanFeatures.C b/applications/utilities/surface/surfaceBooleanFeatures/surfaceBooleanFeatures.C
index 34a69256372..199c1b9a6fc 100644
--- a/applications/utilities/surface/surfaceBooleanFeatures/surfaceBooleanFeatures.C
+++ b/applications/utilities/surface/surfaceBooleanFeatures/surfaceBooleanFeatures.C
@@ -25,16 +25,15 @@ Application
     surfaceBooleanFeatures
 
 Description
-
     Generates the extendedFeatureEdgeMesh for the interface between a boolean
-    operation on two surfaces.  Assumes that the orientation of the surfaces is
-    correct:
+    operation on two surfaces.
 
-    + if the operation is union or intersection, that both surface's normals
+    Assumes that the orientation of the surfaces iscorrect:
+    - if the operation is union or intersection, that both surface's normals
       (n) have the same orientation with respect to a point, i.e. surfaces and b
       are orientated the same with respect to point x:
 
-    @verbatim
+    \verbatim
        _______
       |       |--> n
       |    ___|___             x
@@ -43,14 +42,14 @@ Description
           |       |
           |_______|
 
-    @endverbatim
+    \endverbatim
 
-    + if the operation is a subtraction, the surfaces should be oppositely
+    - if the operation is a subtraction, the surfaces should be oppositely
     oriented with respect to a point, i.e. for (a - b), then b's orientation
     should be such that x is "inside", and a's orientation such that x is
     "outside"
 
-    @verbatim
+    \verbatim
        _______
       |       |--> n
       |    ___|___             x
@@ -59,7 +58,7 @@ Description
           |  n <--|
           |_______|
 
-    @endverbatim
+    \endverbatim
 
     When the operation is peformed - for union, all of the edges generates where
     one surfaces cuts another are all "internal" for union, and "external" for
diff --git a/applications/utilities/surface/surfaceClean/surfaceClean.C b/applications/utilities/surface/surfaceClean/surfaceClean.C
index acea21f0bed..eecdbb5155e 100644
--- a/applications/utilities/surface/surfaceClean/surfaceClean.C
+++ b/applications/utilities/surface/surfaceClean/surfaceClean.C
@@ -25,6 +25,9 @@ Application
     surfaceClean
 
 Description
+    Utility to clean surfaces.
+
+    Current functionality
     - removes baffles
     - collapses small edges, removing triangles.
     - converts sliver triangles into split edges by projecting point onto
diff --git a/applications/utilities/surface/surfaceCoarsen/surfaceCoarsen.C b/applications/utilities/surface/surfaceCoarsen/surfaceCoarsen.C
index 4fcb9b1978d..8df9528b139 100644
--- a/applications/utilities/surface/surfaceCoarsen/surfaceCoarsen.C
+++ b/applications/utilities/surface/surfaceCoarsen/surfaceCoarsen.C
@@ -25,12 +25,15 @@ Application
     surfaceCoarsen
 
 Description
-    Surface coarsening using 'bunnylod':
+    Surface coarsening using `bunnylod'
 
+    Reference:
+    \verbatim
         Polygon Reduction Demo
         By Stan Melax (c) 1998
         mailto:melax@cs.ualberta.ca
         http://www.cs.ualberta.ca/~melax
+    \endverbatim
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/utilities/surface/surfaceInertia/surfaceInertia.C b/applications/utilities/surface/surfaceInertia/surfaceInertia.C
index d4c7a757c96..bdc398fb5d3 100644
--- a/applications/utilities/surface/surfaceInertia/surfaceInertia.C
+++ b/applications/utilities/surface/surfaceInertia/surfaceInertia.C
@@ -26,8 +26,9 @@ Application
 
 Description
     Calculates the inertia tensor, principal axes and moments of a
-    command line specified triSurface. Inertia can either be of the
-    solid body or of a thin shell.
+    command line specified triSurface.
+
+    Inertia can either be of the solid body or of a thin shell.
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/utilities/surface/surfaceRefineRedGreen/surfaceRefineRedGreen.C b/applications/utilities/surface/surfaceRefineRedGreen/surfaceRefineRedGreen.C
index c10397bc01e..d5d1dccd205 100644
--- a/applications/utilities/surface/surfaceRefineRedGreen/surfaceRefineRedGreen.C
+++ b/applications/utilities/surface/surfaceRefineRedGreen/surfaceRefineRedGreen.C
@@ -26,10 +26,16 @@ Application
 
 Description
     Refine by splitting all three edges of triangle ('red' refinement).
+
     Neighbouring triangles (which are not marked for refinement get split
-    in half ('green' refinement). (R. Verfuerth, "A review of a posteriori
+    in half ('green' refinement).
+
+    Reference:
+    \verbatim
+    R. Verfuerth, "A review of a posteriori
     error estimation and adaptive mesh refinement techniques",
     Wiley-Teubner, 1996)
+    \endverbatim
 
 \*---------------------------------------------------------------------------*/
 
diff --git a/applications/utilities/surface/surfaceSplitByTopology/surfaceSplitByTopology.C b/applications/utilities/surface/surfaceSplitByTopology/surfaceSplitByTopology.C
index 93a7caa3655..3a86965d8b3 100644
--- a/applications/utilities/surface/surfaceSplitByTopology/surfaceSplitByTopology.C
+++ b/applications/utilities/surface/surfaceSplitByTopology/surfaceSplitByTopology.C
@@ -22,10 +22,10 @@ License
     along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
 
 Description
+    Strips any baffle parts of a surface.
 
-    Strips any baffle parts of a surface.  A baffle region is one which is
-    reached by walking from an open edge, and stopping when a multiply connected
-    edge is reached.
+    A baffle region is one which is reached by walking from an open edge, and
+    stopping when a multiply connected edge is reached.
 
 \*---------------------------------------------------------------------------*/
 
-- 
GitLab