DOC: solverInfo FO: improve header-file documentation

- TUT: solverInfo FO: add an example to pisoFoam/cavity

src/functionObjects/utilities/solverInfo/solverInfo.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015-2016 OpenFOAM Foundation
-    Copyright (C) 2015-2020 OpenCFD Ltd.
+    Copyright (C) 2015-2021 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -36,13 +36,7 @@ namespace Foam
 namespace functionObjects
 {
     defineTypeNameAndDebug(solverInfo, 0);
-
-    addToRunTimeSelectionTable
-    (
-        functionObject,
-        solverInfo,
-        dictionary
-    );
+    addToRunTimeSelectionTable(functionObject, solverInfo, dictionary);
 }
 }
 
@@ -96,7 +90,7 @@ void Foam::functionObjects::solverInfo::createResidualField
 
     if (!mesh_.foundObject<IOField<scalar>>(residualName))
     {
-        IOField<scalar>* fieldPtr =
+        auto* fieldPtr =
             new IOField<scalar>
             (
                 IOobject
@@ -129,8 +123,8 @@ Foam::functionObjects::solverInfo::solverInfo
     fvMeshFunctionObject(name, runTime, dict),
     writeFile(obr_, name, typeName, dict),
     fieldSet_(mesh_),
-    writeResidualFields_(false),
     residualFieldNames_(),
+    writeResidualFields_(false),
     initialised_(false)
 {
     read(dict);
@@ -147,8 +141,7 @@ bool Foam::functionObjects::solverInfo::read(const dictionary& dict)
 
         fieldSet_.read(dict);
 
-        writeResidualFields_ =
-            dict.getOrDefault("writeResidualFields", false);
+        writeResidualFields_ = dict.getOrDefault("writeResidualFields", false);
 
         residualFieldNames_.clear();
 

src/functionObjects/utilities/solverInfo/solverInfo.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015-2016 OpenFOAM Foundation
-    Copyright (C) 2015-2020 OpenCFD Ltd.
+    Copyright (C) 2015-2021 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -31,7 +31,7 @@ Group
     grpUtilitiesFunctionObjects
 
 Description
-    Writes solver information for a list of user-specified fields
+    Writes solver information for a list of user-specified fields.
 
     Information written to file includes:
     - residual fields
@@ -39,39 +39,60 @@ Description
     - initial residual
     - final residual
     - number of solver iterations
-    - convergecnce flag
+    - convergence flag
+
+    Operands:
+    \table
+      Operand      | Type                | Location
+      input        | -                   | -
+      output file  | dat                 <!--
+               --> | postProcessing/\<FO\>/\<time\>/\<file\>(s)
+      output field | volScalarField(s)   <!--
+               --> | \<time\>/initialResiduals:\<outField\>(s)
+    \endtable
 
 Usage
-    Example of function object specification:
+    Minimal example by using \c system/controlDict.functions:
     \verbatim
-    solverInfo
+    solverInfo1
     {
+        // Mandatory entries (unmodifiable)
         type            solverInfo;
         libs            (utilityFunctionObjects);
+
+        // Mandatory entries (runtime modifiable)
+        fields          (<field1> <field2> ... <fieldN>);
+
+        // Optional entries (runtime modifiable)
+        writeResidualFields true;
+
+        // Inherited entries
         ...
-        fields          (U p);
-        writeResidualFields yes;
     }
     \endverbatim
 
-    Where the entries comprise:
+    where the entries mean:
     \table
-        Property     | Description               | Required    | Default value
-        type         | Type name: solverInfo     | yes         |
-        fields       | List of fields to process | yes         |
-        writeResidualFields | Write the residual fields | no          | no
+      Property     | Description                          | Type | Reqd | Deflt
+      type         | Type name: solverInfo                | word | yes  | -
+      libs         | Library name: utilityFunctionObjects | word | yes  | -
+      fields       | Names of operand fields          | wordList | yes  | -
+      writeResidualFields | Flag to write the initial-residual fields <!--
+                   -->                                    | bool | no   | false
     \endtable
 
-    Output data is written to the dir postProcessing/solverInfo/\<timeDir\>/
+    The inherited entries are elaborated in:
+     - \link functionObject.H \endlink
+     - \link writeFile.H \endlink
 
 See also
-    Foam::functionObject
-    Foam::functionObjects::fvMeshFunctionObject
-    Foam::functionObjects::writeFile
-    Foam::functionObjects::timeControl
+  - Foam::functionObject
+  - Foam::functionObjects::fvMeshFunctionObject
+  - Foam::functionObjects::writeFile
 
 SourceFiles
     solverInfo.C
+    solverInfoTemplates.C
 
 \*---------------------------------------------------------------------------*/
 
@@ -100,17 +121,17 @@ class solverInfo
 {
 protected:
 
-    // Protected data
+    // Protected Data
 
-        //- Fields to process
+        //- Names of operand fields
         solverFieldSelection fieldSet_;
 
-        //- Flag to write the residual as a vol field
-        bool writeResidualFields_;
-
         //- Names of (result) residual fields
         wordHashSet residualFieldNames_;
 
+        //- Flag to write the initial-residual as a vol field
+        bool writeResidualFields_;
+
         //- Initialisation flag
         bool initialised_;
 
@@ -136,9 +157,7 @@ protected:
         void updateSolverInfo(const word& fieldName);
 
 
-private:
-
-    // Private member functions
+    // Generated Methods
 
         //- No copy construct
         solverInfo(const solverInfo&) = delete;
@@ -170,13 +189,13 @@ public:
 
     // Member Functions
 
-        //- Read the controls
+        //- Read solverInfo settings
         virtual bool read(const dictionary&);
 
-        //- Execute, currently does nothing
+        //- Execute solverInfo
         virtual bool execute();
 
-        //- Write the solverInfo
+        //- Write solverInfo results
         virtual bool write();
 };
 

src/functionObjects/utilities/solverInfo/solverInfoTemplates.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015-2016 OpenFOAM Foundation
-    Copyright (C) 2015-2019 OpenCFD Ltd.
+    Copyright (C) 2015-2021 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -51,7 +51,7 @@ void Foam::functionObjects::solverInfo::writeFileHeader
             mesh_.validComponents<Type>()
         );
 
-        for (direction cmpt=0; cmpt<pTraits<Type>::nComponents; cmpt++)
+        for (direction cmpt=0; cmpt<pTraits<Type>::nComponents; ++cmpt)
         {
             if (component(validComponents, cmpt) != -1)
             {

tutorials/incompressible/pisoFoam/RAS/cavity/system/FOsolverInfo

+/*--------------------------------*- C++ -*----------------------------------*\
+| =========                 |                                                 |
+| \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
+|  \\    /   O peration     | Version:  v2012                                 |
+|   \\  /    A nd           | Website:  www.openfoam.com                      |
+|    \\/     M anipulation  |                                                 |
+\*---------------------------------------------------------------------------*/
+
+solverInfo1
+{
+    // Mandatory entries
+    type            solverInfo;
+    libs            (utilityFunctionObjects);
+    fields
+    (
+        k
+        epsilon
+        p
+        U
+    )
+
+    // Optional entries
+    writeResidualFields    true;
+
+    // Optional (inherited) entries
+    writePrecision   16;
+    writeToFile      true;
+    useUserTime      true;
+
+    region          region0;
+    enabled         true;
+    log             true;
+    timeStart       0;
+    timeEnd         1000;
+    executeControl  timeStep;
+    executeInterval 1;
+    writeControl    writeTime;
+    writeInterval   -1;
+}
+
+
+// ************************************************************************* //

tutorials/incompressible/pisoFoam/RAS/cavity/system/controlDict

@@ -47,6 +47,7 @@ runTimeModifiable true;
 
 functions
 {
+    // field function objects
     #include "FOfieldAverage"
     #include "FOadd"
     #include "FOblendingFactor"
@@ -94,6 +95,9 @@ functions
     #include "FOwriteCellVolumes"
     #include "FOyPlus"
     #include "FOzeroGradient"
+
+    // utility function objects
+    #include "FOsolverInfo"
 }