functionObjects: Moved functionObjects namespace documentation into functionObject.H

bin/tools/doxyFilter

@@ -3,7 +3,7 @@
 # =========                 |
 # \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
 #  \\    /   O peration     |
-#   \\  /    A nd           | Copyright (C) 2011-2015 OpenFOAM Foundation
+#   \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
 #    \\/     M anipulation  |
 #------------------------------------------------------------------------------
 # License
@@ -47,7 +47,6 @@ then
         filePath=$realFilePath
     fi
 
-    # dirName=$(echo "$filePath" | sed -e 's@/[^/]*$@@' )
     dirName=${filePath%/[^/]*}
     fileName=${filePath##*/}
 
@@ -57,9 +56,6 @@ then
     */applications/solvers/*.C | */applications/utilities/*.C )
         awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-top.awk
         ;;
-#    */applications/solvers/*.H | */applications/utilities/*.H )
-#        awkScript=$WM_PROJECT_DIR/bin/tools/doxyFilter-ignore.awk
-#        ;;
     esac
 
     awk -f $WM_PROJECT_DIR/bin/tools/doxyFilter-table.awk $1 | \
@@ -70,4 +66,5 @@ then
         -e s@%fileName%@$fileName@g \
         -e s@%dirName%@$dirName@g
 fi
+
 #------------------------------------------------------------------------------

bin/tools/doxyFilter-ignore.awk

@@ -31,6 +31,7 @@
 #       to skip documenting all classes/variables
 #
 #------------------------------------------------------------------------------
+
 BEGIN {
    print "//! @file %filePath%"
    print "//! @cond OpenFOAMIgnoreAppDoxygen"
@@ -41,4 +42,5 @@ BEGIN {
 END {
    print "//! @endcond"
 }
+
 #------------------------------------------------------------------------------

bin/tools/doxyFilter-table.awk

@@ -131,5 +131,3 @@ BEGIN {
         print $0
     }
 }
-
-

bin/tools/doxyFilter-top.awk

@@ -31,16 +31,17 @@
 #       block documents the application itself.
 #
 #------------------------------------------------------------------------------
+
 BEGIN {
     state = 0
 }
 
-# a '/*' at the beginning of a line starts a comment block
+# A '/*' at the beginning of a line starts a comment block
 /^ *\/\*/ {
    state++
 }
 
-# check first line
+# Check first line
 # either started with a comment or skip documentation for the whole file
 FNR == 1 {
    if (!state)
@@ -50,7 +51,7 @@ FNR == 1 {
    }
 }
 
-# a '*/' ends the comment block
+# A '*/' ends the comment block
 # skip documentation for rest of the file
 /\*\// {
     if (state == 1)
@@ -62,7 +63,7 @@ FNR == 1 {
     next
 }
 
-# print everything within the first comment block
+# Print everything within the first comment block
 {
     if (state)
     {

bin/tools/doxyFilter.awk

@@ -52,16 +52,15 @@ BEGIN {
     next
 }
 
-
 /^ *\/\// {
-    # start comment block
+    # Start comment block
     if (state == 1)
     {
         printf "/*! "
         state = 2
     }
 
-    # inside comment block
+    # Inside comment block
     if (state == 2)
     {
         if (!sub(/^ *\/\/  /, ""))
@@ -74,9 +73,8 @@ BEGIN {
     next
 }
 
-
 {
-    # end comment block
+    # End comment block
     if (state == 2)
     {
         printf "*/ "

bin/tools/doxyFilter.sed

@@ -7,7 +7,7 @@
 #     equivalent
 #------------------------------------------------------------------------------
 
-# new FSF address
+# New FSF address
 /^License/,/\*\//{
 /^License/,\%http://www.gnu.org/licenses%{
 s?^License.*?\*\/\
@@ -26,7 +26,7 @@ s?^License.*?\*\/\
 }
 
 
-# remove entry
+# Remove entry
 /^Application *$/{
 N
 N
@@ -34,7 +34,7 @@ d
 }
 
 
-# remove entry
+# Remove entry
 /^Global *$/{
 N
 N
@@ -79,7 +79,7 @@ s/Class *\n *\(.*\) */\\class \1/
 # Group
 #     groupName
 # =>
-# \ingroup namespaceName
+# \ingroup groupName
 #
 /^Group *$/,/^[^ ]/{
 s/^Group//
@@ -108,7 +108,7 @@ s/^    /\\typedef /
 }
 
 
-# add anchor and use \brief
+# Add anchor and use \brief
 # the first paragraph will be 'brief' and the others 'detail'
 /^Description *$/,/^[^ ]/{
 /^Description/c\
@@ -136,7 +136,7 @@ s/^    //
 }
 
 
-# remove ToDo paragraph to avoid them showing on related pages
+# Remove ToDo paragraph to avoid them showing on related pages
 /^To[Dd]o *$/,/^[^ ]/{
 s/^To[Dd]o *$//
 s/^    .*//
@@ -174,10 +174,10 @@ s? *\([a-zA-Z0-9]*\.[a-zA-Z]*\)?  <li><a href="%dirName%/\1">\1</a></li>?
 s/.*\*\//\*\//
 
 
-# convert /heading in source files to bold font and add some space
+# Convert /heading in source files to bold font and add some space
 s#\\heading \(.*\)#<br><b>\1</b>#g
 
-# add a linebreak
+# Add a linebreak
 s#\\linebreak#<br>#g
 
 }

src/OpenFOAM/db/functionObjects/functionObject/functionObject.H

@@ -21,6 +21,70 @@ License
     You should have received a copy of the GNU General Public License
     along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
 
+Namespace
+    Foam::functionObjects
+
+Description
+    Namespace for functionObjects.
+
+    OpenFOAM includes a collection of functionObjects selected by the user at
+    run-time to manipulate the simulation and provide mechanisms to extract
+    field and derived quantities.  Alternatively, the same actions can be
+    executed after the simulation using the \c execFlowFunctionObjects utility.
+
+    \linebreak
+    The current range of features are sub-divided into the following categories:
+    - \ref grpLagrangianFunctionObjects
+    - \ref grpFieldFunctionObjects
+    - \ref grpForcesFunctionObjects
+    - \ref grpUtilitiesFunctionObjects
+
+    \linebreak
+    \subsection secFunctionObjects Using function objects
+
+    FunctionObjects are selected by additional entries in the
+    $FOAM_CASE/system/controlDict dictionary.  Each object is listed in the \c
+    functions sub-dictionary, e.g. to select the \c functionObjectType
+    functionObject the following entry would be specified:
+
+    \verbatim
+        functions
+        {
+            myFunctionObject    // Name of functionObject entry
+            {
+                type                functionObjectType;
+                functionObjectLibs  ("libMyFunctionObjectlib.so");
+                region              defaultRegion;
+                enabled             yes;
+                timeStart           0;
+                timeEnd             10;
+                outputControl       outputTime;
+                outputInterval      1;
+                ...
+            }
+        }
+    \endverbatim
+
+    Where:
+    \table
+        Property | Description                       | Required | Default value
+        type     | Type of function object               | yes      |
+        functionObjectLibs | Libraries containing object implementation | yes |
+        region   | Name of region for multi-region cases | no       |
+        enabled  | On/off switch                         | no       | yes
+        timeStart| Start time                            | no       |
+        timeEnd  | End time                              | no       |
+        outputControl | Either 'outputTime' or 'timeStep'| no | timeStep
+        outputInterval| Steps between output for outputControl=timeStep | no | 1
+    \endtable
+
+    The sub-dictionary name \c myFunctionObject is chosen by the user, and is
+    typically used as the name of the output directory for any data written by
+    the functionObject.  The \c type entry defines the type of function object
+    properties that follow.  FunctionObjects are packaged into separate
+    libraries and the \c libs entry is used to specify which library
+    should be loaded.
+
 Class
     Foam::functionObject
 

src/OpenFOAM/global/foamDoc.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
-    \\  /    A nd           | Copyright (C) 2011-2015 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -23,7 +23,7 @@ License
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-\mainpage OpenFOAM®: open source CFD
+\mainpage OpenFOAM®: Open-Source CFD
 
 \section about About OpenFOAM
 
@@ -36,29 +36,24 @@ License
     turbulence and heat transfer, to solid dynamics and electromagnetics.
     <a href="http://www.openfoam.org/features">More ...</a>
 
+\section layout OpenFOAM Directory Structure
 
-\section layout Code Layout
+    OpenFOAM comprises of four main directories:
-
-    The OpenFOAM source code comprises of four main components:
     - src:
-        the core OpenFOAM source code
+        The core OpenFOAM libraries
 
     - applications:
-        collections of library functionality wrapped up into applications,
+        Solvers and utilities
-        such as solvers and utilities
 
     - tutorials:
-        a suite of test cases that highlight a broad cross-section of
+        Test-cases that demonstrate a wide-range of OpenFOAM functionality
-        OpenFOAM's capabilities
 
     - doc:
-        supporting documentation
+        Documentation
 
-
+\section usingOpenFOAM Using OpenFOAM
-\section usingTheCode Using the code
 
     - \subpage pagePostProcessing
-    - \subpage pageBoundaryConditions
+    - Post-processing using Foam::functionObjects
-
 
 \*---------------------------------------------------------------------------*/

src/postProcessing/functionObjects/doc/functionObjects.dox

@@ -1,91 +0,0 @@
-/*---------------------------------------------------------------------------*\
-  =========                 |
-  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
-   \\    /   O peration     |
-    \\  /    A nd           | Copyright (C) 2012-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
--------------------------------------------------------------------------------
-License
-    This file is part of OpenFOAM.
-
-    OpenFOAM is free software: you can redistribute it and/or modify it under
-    the terms of the GNU General Public License as published by the Free
-    Software Foundation, either version 3 of the License, or (at your option)
-    any later version.
-
-    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT ANY
-    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
-    details.
-
-    You should have received a copy of the GNU General Public License along with
-    OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-\page pagePostProcessing Post-processing
-
-\section secFunctionObjects Function objects
-
-OpenFOAM includes a collection of \ref grpFunctionObjects that offer users the
-opportunity to closely manage their computational analyses.  These objects can
-be applied to manipulate the workflow process, and provide a mechanism to
-extract predicted field and derived quantities at run-time.  Alternatively,
-the actions can be executed afterwards using the \c execFlowFunctionObjects
-utility.
-
-\linebreak
-The current range of features comprises of:
-- \ref grpLagrangianFunctionObjects
-- \ref grpFieldFunctionObjects
-- \ref grpForcesFunctionObjects
-- \ref grpUtilitiesFunctionObjects
-
-\linebreak
-\subsection secFieldFunctionObjectUsage Using function objects
-
-Function objects are defined by additional entries in the
-$FOAM_CASE/system/controlDict input dictionary.  Each object is listed in a
-\c functions sub-dictionary entry, e.g. the following shows the input options
-applicable to `output' -type objects:
-
-\verbatim
-functions
-{
-    myFunctionObject    // user-defined name of function object entry
-    {
-        type                functionObjectType;
-        functionObjectLibs  ("libMyFunctionObjectlib.so");
-        region              defaultRegion;
-        enabled             yes;
-        timeStart           0;
-        timeEnd             10;
-        outputControl       outputTime;
-        outputInterval      1;
-        ...
-    }
-}
-\endverbatim
-
-Where:
-\table
-    Property | Description                           | Required | Default value
-    type     | type of function object               | yes      |
-    functionObjectLibs | libraries containing object implementation | yes |
-    region   | name of region for multi-region cases | no       |
-    enabled  | on/off switch                         | no       | yes
-    timeStart| start time                            | no       |
-    timeEnd  | end time                              | no       |
-    outputControl | when to output: either 'outputTime' or 'timeStep'| no | timeStep
-    outputInterval| steps between output when outputControl=timeStep | no | 1
-\endtable
-
-The sub-dictionary name \c myFunctionObject is chosen by the user, and is
-typically used as the name of the output directory for any derived data.  The
-\c type entry defines the type of function object properties that follow.
-Since the function objects are packaged into separate libraries, the user must
-tell the code where to find the function object implementation, identified
-using the \c libs entry.
-
-
-\*---------------------------------------------------------------------------*/