TUT: update velocityDampingConstraint header (#942)

  STYLE: add getOrDefault(); const specifiers to velocityDampingConstraint

src/fvOptions/constraints/derived/velocityDampingConstraint/velocityDampingConstraint.C

@@ -55,7 +55,7 @@ void Foam::fv::velocityDampingConstraint::addDamping(fvMatrix<vector>& eqn)
     // Note: we want to add
     //      deltaU/deltaT
     // where deltaT is a local time scale:
-    //  U/(cbrt of volume)
+    //      U/(cbrt of volume)
     // Since directly manipulating the diagonal we multiply by volume.
 
     const scalarField& vol = mesh_.V();
@@ -66,10 +66,10 @@ void Foam::fv::velocityDampingConstraint::addDamping(fvMatrix<vector>& eqn)
 
     forAll(U, cellI)
     {
-        scalar magU = mag(U[cellI]);
+        const scalar magU = mag(U[cellI]);
         if (magU > UMax_)
         {
-            scalar scale = sqr(Foam::cbrt(vol[cellI]));
+            const scalar scale = sqr(Foam::cbrt(vol[cellI]));
 
             diag[cellI] += scale*(magU-UMax_);
 
@@ -129,7 +129,7 @@ bool Foam::fv::velocityDampingConstraint::read(const dictionary& dict)
         if (!coeffs_.readIfPresent("UNames", fieldNames_))
         {
             fieldNames_.resize(1);
-            fieldNames_.first() = coeffs_.lookupOrDefault<word>("U", "U");
+            fieldNames_.first() = coeffs_.getOrDefault<word>("U", "U");
         }
 
         applied_.setSize(fieldNames_.size(), false);

src/fvOptions/constraints/derived/velocityDampingConstraint/velocityDampingConstraint.H

@@ -31,28 +31,38 @@ Group
     grpFvOptionsConstraints
 
 Description
-    Constraint for velocity to dampen velocity fluctuations in
-    steady simulations
-
-    In case of velocity exceeding limit applies
-    a source sink to remove the excess velocity by adding a term
-    that drives the velocity to 0 (note that we cannot use the old
-    term velocity since it most likely is already excessive). This
-    additional constraint is scaled with (U-UMax)/dt
-    where dt is a local time scale (= velocity/cellsize) so it switches off
-    if the velocity is below UMax.
-
-    Constraint described by:
-
-        velocityDampingConstraintCoeffs
-        {
-            UMax        100;
-
-            // Optional: name of velocity field (default: U)
-            //U         U;
-            //UNames    (U);
-        }
-
+    Constraint on velocity field to dampen velocity fluctuations.
+
+    This constraint is primarily used to dampen velocity fluctuations in
+    the start-up phase of simulations. When the local velocity magnitude
+    exceeds the user-supplied maximum value a sink term is activated in
+    the affected region to lower the velocity to the limiting value.
+
+Usage
+    Example of functionality specification in \c fvOptions:
+    \verbatim
+    velocityDamper
+    {
+        // Mandatory entries
+        type            velocityDampingConstraint;
+        UMax            200;
+
+        // Optional entries
+        selectionMode   all;
+        UNames          (U);    // names of given velocity fields
+        U               U;      // name of given velocity field if
+                                //`UNames` is not present (default: U)
+
+        // Optional fvOptions entries
+        active          true;
+    }
+    \endverbatim
+
+Note
+    When active, this constraint manipulates the system of equations.
+    Users should ensure that it is not active when the case is converged
+    (steady-state) or during the period of interest (transient) to ensure
+    that its presence does not pollute the results.
 
 SourceFiles
     velocityDampingConstraint.C
@@ -82,9 +92,9 @@ class velocityDampingConstraint
 
 protected:
 
-    // Protected data
+    // Protected Data
 
-        //- Maximum velocity
+        //- Maximum velocity magnitude
         scalar UMax_;