Merge branch 'doc.topoSet' into 'develop'

DOC: Elaborate the usage of topoSet

See merge request Development/openfoam!361

src/meshTools/sets/cellSources/boundaryToCell/boundaryToCell.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,10 +27,49 @@ Class
     Foam::boundaryToCell
 
 Description
-    A topoSetCellSource to select all external (boundary) faces.
+    A \c topoSetCellSource to select all cells possessing
+    at least a single face on all external boundaries.
 
-    \heading Dictionary parameters
+    Operands:
-    None
+    \table
+      Operand   | Type    | Location
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+    \endtable
+
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      boundaryToCell;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of cellSet                      | word |  yes  | -
+      type       | Type name: cellSet                   | word |  yes  | -
+      action     | Action applied on cells - see below  | word |  yes  | -
+      source     | Source name: boundaryToCell          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::patchToCell
 
 SourceFiles
     boundaryToCell.C
@@ -55,7 +94,7 @@ class boundaryToCell
 :
     public topoSetCellSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -71,6 +110,7 @@ public:
     //- Runtime type information
     TypeName("boundaryToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -94,7 +134,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/boxToCell/boxToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,20 +28,80 @@ Class
     Foam::boxToCell
 
 Description
-    A topoSetCellSource to select cells based on cell centres inside box(es).
+    A \c topoSetCellSource to select all cells
+    whose cell centre inside given bounding box(es).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        boxes       | Multiple bounding boxes               | partly   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        box         | A single bounding box                 | partly   |
-        min         | Minimum point for a single box        | partly   |
-        max         | Maximum point for a single box        | partly   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      boxToCell;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        boxes
+        (
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-1
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-2
+            ...
+        );
+
+        // Option-2
+        box (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>);
+
+        // Option-3
+        min (<minX> <minY> <minZ>);
+        max (<maxX> <maxY> <maxZ>);
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: boxToCell              | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type       | Req'd  | Dflt
+      boxes    | Multiple bounding boxes        | vectorList | cond'l | -
+      box      | A single bounding box          | vector     | cond'l | -
+      min      | Minimum point for a single box | vector     | cond'l | -
+      max      | Maximum point for a single box | vector     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "boxes", "box" or a "min/max" pair
+    The order of precedence among the conditional mandatory entries from the
-    (compatibility with searchable box) - highest to lowest precedence.
+    highest to the lowest is \c boxes, \c box or a \c min-max pair
+    (compatibility with \c searchableBox).
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
 
 SourceFiles
     boxToCell.C
@@ -67,7 +127,7 @@ class boxToCell
 :
     public topoSetCellSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -86,6 +146,7 @@ public:
     //- Runtime type information
     TypeName("boxToCell");
 
+
     // Constructors
 
         //- Construct from components, copying bounding boxes

src/meshTools/sets/cellSources/cellToCell/cellToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,73 @@ Class
     Foam::cellToCell
 
 Description
-    A topoSetCellSource to select the cells from another cellSet.
+    A \c topoSetCellSource to select all the cells from given \c cellSet(s).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                          | Required | Default
+      Operand   | Type       | Location
-        sets        | The input cellSet names              | possibly |
+      input     | cellSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The input cellSet name               | possibly |
+      output    | cellSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      cellToCell;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <cellSetName1>
+            <cellSetName2>
+            ...
+        );
+
+        // Option-2
+        set <cellSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: cellToCell             | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type     | Req'd  | Dflt
+      sets     | Names of input cellSets        | wordList | cond'l | -
+      set      | Name of input cellSet          | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
 
 SourceFiles
     cellToCell.C
@@ -63,7 +119,7 @@ class cellToCell
 :
     public topoSetCellSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -77,6 +133,7 @@ public:
     //- Runtime type information
     TypeName("cellToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -100,7 +157,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/cylinderAnnulusToCell/cylinderAnnulusToCell.C

@@ -121,7 +121,15 @@ Foam::cylinderAnnulusToCell::cylinderAnnulusToCell
     point2_(point2),
     radius_(radius),
     innerRadius_(innerRadius)
-{}
+{
+    if (innerRadius_ > radius_)
+    {
+        FatalErrorInFunction
+            << "inner radius = " << innerRadius_ << "cannot be larger than "
+            << "outer radius = " << radius_
+            << exit(FatalIOError);
+    }
+}
 
 
 Foam::cylinderAnnulusToCell::cylinderAnnulusToCell
@@ -135,8 +143,8 @@ Foam::cylinderAnnulusToCell::cylinderAnnulusToCell
         mesh,
         dict.get<point>("p1"),
         dict.get<point>("p2"),
-        dict.get<scalar>("outerRadius"),
+        dict.getCheck<scalar>("outerRadius", scalarMinMax::ge(SMALL)),
-        dict.get<scalar>("innerRadius")
+        dict.getCheck<scalar>("innerRadius", scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/cellSources/cylinderAnnulusToCell/cylinderAnnulusToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,19 +27,64 @@ License
 Class
     Foam::cylinderAnnulusToCell
 
-Description
+Group
-    A topoSetCellSource to select cells based on cell centres inside a
+    grpCellSources
-    cylinder annulus.
 
-    \heading Dictionary parameters
+Description
+    A \c topoSetCellSource to select all cells whose cell
+    centre inside a given bounding cylinder annulus.
+
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        p1          | Coordinate of endpoint            | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        p2          | Coordinate of endpoint            | yes   |
-        outerRadius | Cylinder outer radius             | yes   |
-        innerRadius | Cylinder inner radius             | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name           <name>;
+        type           cellSet;
+        action         <action>;
+
+        // Mandatory entries
+        source         cylinderAnnulusToCell;
+        p1             (<p1X> <p1Y> <p1Z>);
+        p2             (<p2X> <p2Y> <p2Z>);
+        outerRadius    <radius1>;
+
+        // Optional entries
+        innerRadius    <radius2>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type   | Req'd | Dflt
+      name       | Name of cellSet                     | word   |  yes  | -
+      type       | Type name: cellSet                  | word   |  yes  | -
+      action     | Action applied on cells - see below | word   |  yes  | -
+      source     | Source name: cylinderAnnulusToCell  | word   |  yes  | -
+      p1          | Coordinate of one of the endpoints | vector |  yes  | -
+      p2          | Coordinate of the other endpoint   | vector |  yes  | -
+      outerRadius | Cylinder outer radius              | scalar |  yes  | -
+      innerRadius | Cylinder inner radius              | scalar |  no   | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::cylinderToCell
+
 SourceFiles
     cylinderAnnulusToCell.C
 
@@ -63,8 +108,7 @@ class cylinderAnnulusToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -123,7 +167,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/cylinderToCell/cylinderToCell.C

@@ -110,7 +110,15 @@ Foam::cylinderToCell::cylinderToCell
     point2_(point2),
     radius_(radius),
     innerRadius_(innerRadius)
-{}
+{
+    if (innerRadius_ > radius_)
+    {
+        FatalErrorInFunction
+            << "inner radius = " << innerRadius_ << "cannot be larger than "
+            << "outer radius = " << radius_
+            << exit(FatalIOError);
+    }
+}
 
 
 Foam::cylinderToCell::cylinderToCell
@@ -124,8 +132,8 @@ Foam::cylinderToCell::cylinderToCell
         mesh,
         dict.get<point>("p1"),
         dict.get<point>("p2"),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(SMALL)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/cellSources/cylinderToCell/cylinderToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,60 @@ Class
     Foam::cylinderToCell
 
 Description
-    A topoSetCellSource to select cells with their centres inside a cylinder.
+    A \c topoSetCellSource to select all cells whose cell centre
+    inside a given bounding cylinder or cylinder annulus.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required | Default
+      Operand   | Type    | Location
-        p1          | Coordinate of endpoint            | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        p2          | Coordinate of endpoint            | yes   |
-        radius      | Cylinder (outer) radius           | yes   |
-        innerRadius | Cylinder inner radius             | no    | 0
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name           <name>;
+        type           cellSet;
+        action         <action>;
+
+        // Mandatory entries
+        source         cylinderToCell;
+        p1             (<p1X> <p1Y> <p1Z>);
+        p2             (<p2X> <p2Y> <p2Z>);
+        radius         <radius1>;
+
+        // Optional entries
+        innerRadius    <radius2>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type   | Req'd | Dflt
+      name       | Name of cellSet                     | word   |  yes  | -
+      type       | Type name: cellSet                  | word   |  yes  | -
+      action     | Action applied on cells - see below | word   |  yes  | -
+      source     | Source name: cylinderToCell         | word   |  yes  | -
+      p1          | Coordinate of one of the endpoints | vector |  yes  | -
+      p2          | Coordinate of the other endpoint   | vector |  yes  | -
+      radius      | Cylinder outer radius              | scalar |  yes  | -
+      innerRadius | Cylinder inner radius              | scalar |  no   | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::cylinderAnnulusToCell
+
 SourceFiles
     cylinderToCell.C
 
@@ -62,8 +105,7 @@ class cylinderToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -122,7 +164,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/faceToCell/faceToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,86 @@ Class
     Foam::faceToCell
 
 Description
-    A topoSetCellSource to select cells based on usage in a face set.
+    A \c topoSetCellSource to select all cells based on usage in given
+    \c faceSet(s), e.g. select cells that are the \c owner/neighbour/any
+    of the faces in a given \c faceSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type       | Location
-        sets        | The faceSet names to use              | possibly |
+      input     | faceSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The faceSet name to use               | possibly |
+      output    | cellSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection type (all/any/owner/neighbour)  | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      faceToCell;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <faceSetName0>
+            <faceSetName1>
+            ...
+        );
+
+        // Option-2
+        set     <faceSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: faceToCell             | word |  yes  | -
+      option     | Selection type - see below          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      all       | Cells that are either owner or neighbour of given faces
+      any       | Cells that are either owner or neighbour of given faces
+      owner     | Cells that are owner of given faces
+      neighbour | Cells that are neighbour of given faces
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input faceSets    | wordList | cond'l | -
+      set      | Name of input faceSet      | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::faceZoneToCell
 
 SourceFiles
     faceToCell.C
@@ -75,10 +143,12 @@ public:
             NEIGHBOUR
         };
 
+
 private:
 
-        static const Enum<faceAction> faceActionNames_;
+    // Private Data
 
+        static const Enum<faceAction> faceActionNames_;
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -130,7 +200,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/faceZoneToCell/faceZoneToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,19 +28,83 @@ Class
     Foam::faceZoneToCell
 
 Description
-    A topoSetCellSource to select cells based on side of faceZone.
+    A \c topoSetCellSource to select cells based on \c master
+    or \c slave side of given \c faceZone(s).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type        | Location
-        option      | Selection type (master / slave)       | yes   |
+      input     | faceZone(s) | $FOAM_CASE/constant/polyMesh/faceZones
-        zones       | The face zone names or regexs         | possibly |
+      output    | cellSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        zone        | The face zone name or regex           | possibly |
-        name        | Older specification for 'zone'        | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      faceZoneToCell;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        zones
+        (
+            <faceZoneName1>
+            <faceZoneName2>
+            ...
+        );
+
+        // Option-2
+        set <faceZoneName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: faceZoneToCell         | word |  yes  | -
+      option     | Selection type - see below          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      master   | Master side of the faceZone
+      slave    | Slave side of the faceZone
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type     | Req'd  | Dflt
+      zones    | Names of input faceZones       | wordList | cond'l | -
+      zone     | Name of input faceZone         | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "zones", "zone" or "name" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c zones, and \c zone.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::faceToCell
 
 SourceFiles
     faceZoneToCell.C
@@ -74,9 +138,10 @@ public:
             SLAVE
         };
 
+
 private:
 
-    // Private data
+    // Private Data
 
         static const Enum<faceAction> faceActionNames_;
 
@@ -86,7 +151,7 @@ private:
         //- Matcher for face zones
         wordRes selectedZones_;
 
-        //- Option
+        //- Selection type
         faceAction option_;
 
 
@@ -100,6 +165,7 @@ public:
     //- Runtime type information
     TypeName("faceZoneToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -128,7 +194,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/fieldToCell/fieldDictionary.H

@@ -6,6 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
+    Copyright (C) 2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -51,17 +52,14 @@ class fieldDictionary
     public regIOobject,
     public dictionary
 {
-    const word type_;
+
+    // Private Data
+
+        const word type_;
+
 
 public:
 
-    // Redefine type name to be of the instantiated type
-    virtual const word& type() const
-    {
-        return type_;
-    }
-
-
     // Constructors
 
         //- Construct from ioobject and overloaded typename.
@@ -75,8 +73,13 @@ public:
         }
 
 
+    // Member Functions
 
-    // Member functions
+        //- Redefine type name to be of the instantiated type
+        virtual const word& type() const
+        {
+            return type_;
+        }
 
         bool writeData(Ostream& os) const
         {

src/meshTools/sets/cellSources/fieldToCell/fieldToCell.C

@@ -131,7 +131,15 @@ Foam::fieldToCell::fieldToCell
     fieldName_(fieldName),
     min_(min),
     max_(max)
-{}
+{
+    if (min_ > max_)
+    {
+        WarningInFunction
+            << "Input min value = " << min_ << " is larger than "
+            << "input max value = " << max_ << " for field = " << fieldName_
+            << endl;
+    }
+}
 
 
 Foam::fieldToCell::fieldToCell

src/meshTools/sets/cellSources/fieldToCell/fieldToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,16 +28,56 @@ Class
     Foam::fieldToCell
 
 Description
-    A topoSetCellSource to select cells based on field values.
+    A \c topoSetCellSource to select cells based on \c volScalarField values,
+    i.e. select cells with given field value of >= min and <= max.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand  | Type           | Location
-        field       | The (scalar, vector) field to use | yes   |
+      input    | volScalarField | $FOAM_CASE/\<time\>/\<inpField\>
-        min         | The min value for the subset      | yes   |
+      output   | cellSet        | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        max         | The max value for the subset      | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      fieldToCell;
+        field       <fieldName>;
+        min         <minFieldValue>;
+        max         <maxFieldValue>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: fieldToCell            | word |  yes  | -
+      field      | Name of volScalarField to use       | word |  yes  | -
+      min        | The min value for the subset        | scalar | yes | -
+      max        | The max value for the subset        | scalar | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     fieldToCell.C
 
@@ -62,13 +102,11 @@ class fieldToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
 
-
         //- Name of volScalarField, volVectorField
         word fieldName_;
 
@@ -89,11 +127,13 @@ class fieldToCell
             topoSet& set
         ) const;
 
+
 public:
 
     //- Runtime type information
     TypeName("fieldToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -123,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/haloToCell/haloToCell.C

@@ -208,7 +208,8 @@ void Foam::haloToCell::applyToSet
     {
         if (verbose_)
         {
-            Info<< "    Cannot create new of halo (needs a starting set)"
+            Info<< "    action=new option is not available for haloToCell" << nl
+                << "    Cannot create new of halo (needs a starting set)"
                 << endl;
         }
 

src/meshTools/sets/cellSources/haloToCell/haloToCell.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2019 OpenCFD Ltd.
+    Copyright (C) 2019-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,58 @@ Class
     Foam::haloToCell
 
 Description
-    A topoSetCellSource to add/remove halo cells (cells attached to
+    A \c topoSetCellSource to select cells attached to the outside
-    the outside of the current cellSet).
+    of this \c cellSet, and add into/remove from this \c cellSet.
-    When removing halo cells, this strips off any cells on the boundary
-    of the set.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand  | Type    | Location
-        steps       | Number of grow/shrink steps to use    | no  | 1
+      input    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output   | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      haloToCell;
+
+        // Optional entries
+        steps       1;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: haloToCell             | word |  yes  | -
+      steps      | Number of grow/shrink steps to use  | label | no   | 1
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+Note
+    - \c action=new is not available for \c haloToCell.
+    - When removing halo cells, this strips off
+    any cells on the boundary of the cellSet.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     haloToCell.C
 
@@ -61,8 +102,7 @@ class haloToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -105,7 +145,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/labelToCell/labelToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,56 @@ Class
     Foam::labelToCell
 
 Description
-    A topoSetCellSource to select cells based on explicitly given labels.
+    A \c topoSetCellSource to select cells
+    based on explicitly given cell labels.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        value       | The cell labels                   | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      labelToCell;
+        value
+        (
+            <cellLabel1>
+            <cellLabel2>
+            ...
+        );
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: labelToCell            | word |  yes  | -
+      value      | Input cell labels                   | labelList | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     labelToCell.C
 
@@ -59,8 +101,7 @@ class labelToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -74,6 +115,7 @@ public:
     //- Runtime type information
     TypeName("labelToCell");
 
+
     // Constructors
 
         //- Construct from components, copying labels
@@ -100,7 +142,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/nbrToCell/nbrToCell.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -131,7 +131,7 @@ Foam::nbrToCell::nbrToCell
     const dictionary& dict
 )
 :
-    nbrToCell(mesh, dict.get<label>("neighbours"))
+    nbrToCell(mesh, dict.getCheck<label>("neighbours", labelMinMax::ge(1)))
 {}
 
 

src/meshTools/sets/cellSources/nbrToCell/nbrToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,15 +28,52 @@ Class
     Foam::nbrToCell
 
 Description
-    A topoSetCellSource to select cells based on number of neighbouring cells
+    A \c topoSetCellSource to select cells with \c N or less number
-    (i.e. number of internal or coupled faces)
+    of neighbouring cells (i.e. number of internal or coupled faces).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        neighbours  | Number of neighbours              | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      nbrToCell;
+        neighbours  <number>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: nbrToCell              | word |  yes  | -
+      neighbours  | Maximum number of neighbour cells  | label | yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::haloToCell
+
 SourceFiles
     nbrToCell.C
 
@@ -60,8 +97,7 @@ class nbrToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -104,7 +140,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/nearestToCell/nearestToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,56 @@ Class
     Foam::nearestToCell
 
 Description
-    A topoSetCellSource to select cells nearest to points.
+    A \c topoSetCellSource to select cells
+    whose cell centre nearest to given points.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        points      | List of selection points          | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      nearestToCell;
+        points
+        (
+            (<p1x> <p1y> <p1z>)
+            (<p2x> <p2y> <p2z>)
+            ...
+        );
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: nearestToCell          | word |  yes  | -
+      points     | List of selection points     | vectorList  |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     nearestToCell.C
 
@@ -59,8 +101,7 @@ class nearestToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -79,6 +120,7 @@ public:
     //- Runtime type information
     TypeName("nearestToCell");
 
+
     // Constructors
 
         //- Construct from components, copying points
@@ -105,7 +147,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/patchToCell/patchToCell.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,73 @@ Class
     Foam::patchToCell
 
 Description
-    A topoSetCellSource to select cells associated with patches.
+    A \c topoSetCellSource to select cells associated with given patch(es).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        patches     | The patch names or regexs             | possibly |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        patch       | The patch name or regex               | possibly |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      patchToCell;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        patches
+        (
+            <patchName1>
+            <patchName2>
+            ...
+        );
+
+        // Option-2
+        patch    <patchName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: patchToCell            | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                   | Type     | Req'd  | Dflt
+      patches  | Names of patches or wildcards | wordList | cond'l | -
+      patch    | Name of patch or wildcard     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "patches" or "patch" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c patches, and \c patch.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+    - Foam::boundaryToCell
 
 SourceFiles
     patchToCell.C
@@ -105,7 +161,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/pointToCell/pointToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2012 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,82 @@ Class
     Foam::pointToCell
 
 Description
-    A topoSetCellSource to select cells based on usage of points.
+    A \c topoSetCellSource to select cells with any
+    point or any edge within a given \c pointSet(s).
 
-    \heading Dictionary parameters
+    Operands
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type         | Location
-        sets        | The pointSet names to use         | possibly |
+      input     | pointSeti(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The pointSet name to use          | possibly |
+      output    | cellSet      | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection type (any/edge)         | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      pointToCell;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <pointSetName1>
+            <pointSetName2>
+            ...
+        );
+
+        // Option-2
+        set   <pointSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: pointToCell            | word |  yes  | -
+      option     | Selection type - see below          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      any     | Cells using any point in pointSet
+      edge    | Cells using an edge with both points in pointSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input pointSets   | wordList | cond'l | -
+      set      | Name of input pointSet     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
 
 SourceFiles
     pointToCell.C
@@ -74,8 +138,11 @@ public:
             //ALL   // Possible extension: cells whose all points are in set
         };
 
+
 private:
 
+    //Private Data
+
         //- Add usage string
         static addToUsageTable usage_;
 
@@ -84,7 +151,7 @@ private:
         //- Names of sets to use
         wordList names_;
 
-        //- Option
+        //- Selection type
         pointAction option_;
 
 
@@ -99,6 +166,7 @@ public:
     //- Runtime type information
     TypeName("pointToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -127,7 +195,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/regionToCell/regionToCell.C

@@ -410,7 +410,7 @@ Foam::regionToCell::regionToCell
     (
         dict.getCompat<pointField>("insidePoints", {{ "insidePoint", 0 }})
     ),
-    nErode_(dict.getOrDefault<label>("nErode", 0))
+    nErode_(dict.getCheckOrDefault<label>("nErode", 0, labelMinMax::ge(0)))
 {}
 
 

src/meshTools/sets/cellSources/regionToCell/regionToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2012 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,31 +28,66 @@ Class
     Foam::regionToCell
 
 Description
-    A topoSetCellSource to select cells belonging to a topological connected
+    A \c topoSetCellSource to select cells belonging to a topologically
-    region (that contains given points)
+    connected region (that contains given points). If started inside
+    a given \c subCellSet keeps to it; if started outside stays outside.
+
+    Operands:
+    \table
+      Operand   | Type    | Location
+      input     | region  | $FOAM_CASE/constant/\{\<region\>, polyMesh\}
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+    \endtable
 
 Usage
-    In dictionary input:
+    Minimal example by using \c system/topoSetDict.actions:
     \verbatim
-        // optional name of cellSet delimiting search
+    {
-        set         c0;
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
 
-        //- Number of cell layers to erode mesh to detect holes in the mesh
+        // Mandatory entries
-        //  Set to 0 if not used.
+        source      regionToCell;
-        nErode 3;
+        insidePoints
+        (
+            (<p1x> <p1y> <p1z>)
+            (<p2x> <p2y> <p2z>)
+            ...
+        );
 
-        // points inside region to select
+        // Optional entries
-        insidePoints ((1 2 3));
+        set       <cellSetName>;
+        nErode    <label>;
+    }
     \endverbatim
 
-    Dictionary parameters:
+    where the entries mean:
     \table
-        Property    | Description                           | Required | Default
+      Property   | Description                         | Type | Req'd | Dflt
-        insidePoints | Points inside regions                | yes   |
+      name       | Name of cellSet                     | word |  yes  | -
-        nErode      | Cell layers to erode to detect holes  | no | 0
+      type       | Type name: cellSet                  | word |  yes  | -
-        set         | Restrict to named cellSet             | no    | ""
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: regionToCell           | word |  yes  | -
+      insidePoints  | Coordinate(s) that is inside connected region <!--
+                                             --> | vectorList |  yes  | -
+      set        | Name of cellSet giving mesh subset  | word |  no   | none
+      nErode     | Number of cell layers to erode mesh to detect holes <!--
+           --> in the mesh - set to 0 if not used      | label | no   | 0
     \endtable
 
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     regionToCell.C
 
@@ -79,8 +114,7 @@ class regionToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -105,7 +139,7 @@ class regionToCell
         ) const;
 
         //- Determine for every disconnected region in the mesh whether
-        //  it contains a locationInMesh
+        //- it contains a locationInMesh
         boolList findRegions(const bool verbose, const regionSplit&) const;
 
         //- Unselect regions not containing a locationInMesh
@@ -115,7 +149,7 @@ class regionToCell
         void shrinkRegions(boolList& selectedCell) const;
 
         //- Erode a given number of layers from selectedCell. Remove any
-        //  region that gets disconnected that way.
+        //- region that gets disconnected that way.
         void erode(boolList& selectedCell) const;
 
         void combine(topoSet& set, const bool add) const;
@@ -126,6 +160,7 @@ public:
     //- Runtime type information
     TypeName("regionToCell");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/cellSources/rotatedBoxToCell/rotatedBoxToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,28 +28,67 @@ Class
     Foam::rotatedBoxToCell
 
 Description
-    A topoSetCellSource to select cells based on cell centres inside
+    A \c topoSetCellSource to select cells based on cell centres
-    rotated/skewed box (parallelopiped?).
+    inside a given parallopiped (i.e. rotated/skewed box).
 
-    Box defined as origin and i,j,k vectors.
+    Operands:
-    E.g. box rotated 45 degrees around z-axis with sizes sqrt(0.2^2+0.2^2)
+    \table
-    (and extra large, 200 in z direction):
+      Operand   | Type     | Location
+      output    | cellSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+    \endtable
+
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
     \verbatim
-       origin   ( 0.4 0.4 -100);
+    {
-       i        ( 0.2 0.2    0);
+        // Mandatory (inherited) entries
-       j        (-0.2 0.2    0);
+        name        <name>;
-       k        ( 0.0 0.0  100);
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      rotatedBoxToCell;
+        origin      (<o1> <o2> <o3>);
+        i           (<i1> <i2> <i3>);
+        j           (<j1> <j2> <j3>);
+        k           (<k1> <k2> <k3>);
+    }
     \endverbatim
 
-    \heading Dictionary parameters
+    where the entries mean:
     \table
-        Property    | Description                       | Required  | Default
+      Property   | Description                         | Type | Req'd | Dflt
-        origin      | The box  centre                   | yes   |
+      name       | Name of cellSet                     | word |  yes  | -
-        i           |                                   | yes   |
+      type       | Type name: cellSet                  | word |  yes  | -
-        j           |                                   | yes   |
+      action     | Action applied on cells - see below | word |  yes  | -
-        k           |                                   | yes   |
+      source     | Source name: rotateTedBoxToCell     | word |  yes  | -
+      origin     | Origin of the box                   | vector | yes | -
+      i          | x1-axis                             | vector | yes | -
+      j          | x2-axis                             | vector | yes | -
+      k          | x3-axis                             | vector | yes | -
     \endtable
 
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Box defined as origin and i,j,k vectors.
+    For example, box rotated 45 degrees around z-axis with
+    sizes sqrt(0.2^2+0.2^2) (and extra large, 200 in z direction):
+    \verbatim
+      origin   ( 0.4 0.4 -100);
+      i        ( 0.2 0.2  0);
+      j        (-0.2 0.2  0);
+      k        ( 0.0 0.0  200);
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     rotatedBoxToCell.C
 
@@ -74,14 +113,12 @@ class rotatedBoxToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
 
-
+        //- Definition of the parallelopiped (i.e. rotated/skewed box)
-        //- Skewed box
         const point origin_;
         const vector i_;
         const vector j_;
@@ -98,6 +135,7 @@ public:
     //- Runtime type information
     TypeName("rotatedBoxToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -128,7 +166,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/searchableSurfaceToCell/searchableSurfaceToCell.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,56 @@ Class
     Foam::searchableSurfaceToCell
 
 Description
-    A topoSetCellSource to select cells with centres within a
+    A \c topoSetCellSource to select cells whose cell
-    searchableSurface.
+    centre enclosed by a given \c searchableSurface.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type        | Location
-        surfaceType | The searchable surface type           | yes   |
+      input     | triSurface  | $FOAM_CASE/constant/triSurface/\<file\>
-        surfaceName | Name for the IOobject                 | no    | mesh-name
+      output    | cellSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        surface     | Same as 'surfaceType'                 | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      searchableSurfaceToCell;
+        surfaceType <surfaceTypeName>;
+
+        // Optional entries
+        surfaceName <surfaceName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: searchableSurfaceToCell | word |  yes | -
+      surfaceType | The searchable surface type        | word |  yes  | -
+      surfaceName | Name for the IOobject              | word | no | mesh-name
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     searchableSurfaceToCell.C
 

src/meshTools/sets/cellSources/shapeToCell/shapeToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,69 @@ Class
     Foam::shapeToCell
 
 Description
-    A topoSetCellSource to select cells based on cell shape.
+    A \c topoSetCellSource to select cells
+    based on the type of their cell shapes.
 
-    Handles all known ones from static collection in cellModel
+    Handles all types of cell shapes known from static collection
-    and splitHex with 10 degrees feature angle.
+    in the \c cellModel (as shown below) and \c splitHex with
+    10 degrees feature angle.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        shape       | The cell model (hex, ..)              | yes |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        type        | Older specification for 'shape'       | no  |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      shapeToCell;
+        shape       <shapeTypeName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: shapeToCell            | word |  yes  | -
+      shape      | Type of cell shape - see below      | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the \c shape entry:
+    \verbatim
+      splitHex   | Split-hexahedra cells
+      hex        | Hexahedra cells
+      wedge      | Wedge cells
+      tetWedge   | Tetrahedra-wedge cells
+      prism      | Prism cells
+      pyr        | Pyramid cells
+      tet        | Tetrahedra cells
+    \endverbatim
+
+Note
+    \c splitHex hardcoded with internal angle < 10 degrees.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     shapeToCell.C
 
@@ -63,8 +114,7 @@ class shapeToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -75,7 +125,6 @@ class shapeToCell
 
     // Private Member Functions
 
-        //- Depending on cell type add to or delete from cellSet.
         void combine(topoSet& set, const bool add) const;
 
 
@@ -85,7 +134,7 @@ public:
     TypeName("shapeToCell");
 
 
-    // Static data
+    // Static Data
 
         //- Cos of feature angle for polyHedral to be splitHex
         static scalar featureCos;
@@ -114,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/sphereToCell/sphereToCell.C

@@ -114,8 +114,8 @@ Foam::sphereToCell::sphereToCell
     (
         mesh,
         dict.getCompat<vector>("origin", {{"centre", -1806}}),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(0)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/cellSources/sphereToCell/sphereToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,57 @@ Class
     Foam::sphereToCell
 
 Description
-    A topoSetCellSource to select cells based on cell centres inside sphere.
+    A \c topoSetCellSource to select cells based
+    on cell centres inside a given bounding sphere.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        origin      | The origin (centre) of the sphere     | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        radius      | The (outer) radius of sphere          | yes   |
-        innerRadius | The inner radius of sphere            | no    | 0
-        centre      | Alternative for 'origin'              | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      sphereToCell;
+        origin      (0 0 0);
+        radius      0.5;
+
+        // Optional entries
+        innerRadius 0;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: sphereToCell           | word |  yes  | -
+      origin     | The origin (centre) of the sphere   | vector | yes | -
+      radius     | The (outer) radius of sphere        | scalar | yes | -
+      innerRadius | The inner radius of sphere         | scalar | no  | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     sphereToCell.C
 
@@ -62,8 +102,7 @@ class sphereToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -118,7 +157,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/surfaceToCell/surfaceToCell.H

@@ -28,32 +28,88 @@ Class
     Foam::surfaceToCell
 
 Description
-    A topoSetCellSource to select cells based on relation to surface.
+    A \c topoSetCellSource to select cells based on
+    relation to a surface given by an external file.
 
-    Selects:
+    \c surfaceToCell can select:
-    - all cells inside/outside/cut by surface
+    - all cells inside/outside/cut by a surface
-    - all cells inside/outside surface ('useSurfaceOrientation', requires closed
+    - all cells inside/outside surface (\c useSurfaceOrientation,
-      surface)
+    requires closed surface)
     - cells with centre nearer than XXX to surface
     - cells with centre nearer than XXX to surface \b and with normal
       at nearest point to centre and cell-corners differing by
-      more than YYY (i.e., point of high curvature)
+      more than YYY (i.e. point of high curvature)
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand    | Type       | Location
-        file        | The surface "filename"            | yes   |
+      input      | triSurface | $FOAM_CASE/constant/triSurface/\<file\>
-        fileType    | The surface format                | no    |
+      output     | cellSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        scale       | Surface scaling factor            | no    | -1
-        nearDistance | Near distance to the surface     | yes   |
-        curvature    | surface curvature selection      | yes   |
-        outsidePoints| Points outside of surface        | yes   |
-        includeCut     | Include cut cells (bool)       | yes   |
-        includeInside  | Include inside cells (bool)    | yes   |
-        includeOutside | Include outside cells (bool)   | yes   |
-        useSurfaceOrientation | useSurfaceOrientation   | no    | false
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name            <name>;
+        type            cellSet;
+        action          <action>;
+
+        // Mandatory entries
+        source          surfaceToCell;
+        file            <surfaceFileName>;
+        outsidePoints
+        (
+            (<p1x> <p1y> <p1z>)
+            (<p2x> <p2y> <p2z>)
+            ...
+        );
+        includeCut      false;
+        includeInside   false;
+        includeOutside  true;
+        nearDistance    0.5;
+        curvature       1.0;
+
+        // Optional entries
+        useSurfaceOrientation false;
+        fileType        stl;
+        scale           2.0;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: surfaceToCell          | word |  yes  | -
+      file       | The surface "filename"              | word |  yes  | -
+      outsidePoints | List of points that define outside of the surface <!--
+                                                   --> | vectorList | yes | -
+      includeCut | Flag to include cut cells           | bool |  yes  | -
+      includeInside | Flag to include inside cells     | bool |  yes  | -
+      includeOutside | Flag to include outside cells   | bool |  yes  | -
+      useSurfaceOrientation | Flag to use inherently the orientation of <!--
+                            --> the surface            | bool |  no   | false
+      nearDistance | Near distance to the surface      | scalar | yes | -
+      curvature    | Surface curvature                 | scalar | yes | -
+      fileType     | The format of the surface file    | word   | no  | ""
+      scale        | Surface scaling factor            | scalar | no  | -1
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     surfaceToCell.C
 

src/meshTools/sets/cellSources/targetVolumeToCell/targetVolumeToCell.C

@@ -304,7 +304,7 @@ Foam::targetVolumeToCell::targetVolumeToCell
     targetVolumeToCell
     (
         mesh,
-        dict.get<scalar>("volume"),
+        dict.getCheck<scalar>("volume", scalarMinMax::ge(0)),
         dict.get<vector>("normal"),
         dict.getOrDefault<word>("set", "")
     )

src/meshTools/sets/cellSources/targetVolumeToCell/targetVolumeToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2012 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,57 @@ Class
     Foam::targetVolumeToCell
 
 Description
-    A topoSetCellSource to select cells based on the wanted volume of selected
+    A \c topoSetCellSource to select cells based on a target
-    cells. Adapts a plane until it has enough.
+    volume of cells. Adapts a plane until it has enough.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        volume      | The target volume (m^3)           | yes   |
+      output    | cellSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        normal      | The plane normal                  | yes   |
-        set         | Restrict to named cellSet         | no    | ""
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      targetVolumeToCell;
+        volume      10;
+        normal      (1 0 0);
+
+        // Optional entries
+        set         <cellSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: targetVolumeToCell     | word |  yes  | -
+      volume     | The target volume [m3]              | scalar | yes | -
+      normal     | The plane normal                    | vector | yes | -
+      set        | Restrict to named cellSet           | word |  no   | ""
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
+
 SourceFiles
     targetVolumeToCell.C
 
@@ -65,13 +105,12 @@ class targetVolumeToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
 
-        //- Wanted volume
+        //- Target volume
         const scalar vol_;
 
         //- Normal of plane to sweep
@@ -101,6 +140,7 @@ public:
     //- Runtime type information
     TypeName("targetVolumeToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -130,7 +170,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellSources/topoSetCellSource/topoSetCellSource.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,7 +27,11 @@ Class
     Foam::topoSetCellSource
 
 Description
-    Base class of a topoSet source for selecting cells.
+    The \c topoSetCellSource is a intermediate class
+    for handling \c topoSet sources for selecting cells.
+
+    The class is not an executable \c topoSet itself,
+    yet a provider for common entries to its derived \c topoSet.
 
 SourceFiles
     topoSetCellSource.C

src/meshTools/sets/cellSources/zoneToCell/zoneToCell.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,73 @@ Class
     Foam::zoneToCell
 
 Description
-    A topoSetCellSource to select cells based on one or more cellZones.
+    A \c topoSetCellSource to convert \c cellZone(s) to a \c cellSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type        | Location
-        zones       | The cell zone names or regexs         | possibly |
+      input     | cellZone(s) | $FOAM_CASE/constant/polyMesh/cellZones
-        zone        | The cell zone name or regex           | possibly |
+      output    | cellSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        name        | Older specification for 'zone'        | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      zoneToCell;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        zones
+        (
+            <cellZoneName0>
+            <cellZoneName1>
+            ...
+        );
+
+        // Option-2
+        zone     <cellZoneName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellSet                     | word |  yes  | -
+      type       | Type name: cellSet                  | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: zoneToCell             | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellSet from selected cells
+      add      | Add selected cells into this cellsSet
+      subtract | Remove selected cells from this cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      zones    | Names of input cellZones   | wordList | cond'l | -
+      zone     | Name of input cellZone     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "zones", "zone" or "name" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c zones, and \c zone.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetCellSource
 
 SourceFiles
     zoneToCell.C
@@ -65,8 +120,7 @@ class zoneToCell
 :
     public topoSetCellSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -85,6 +139,7 @@ public:
     //- Runtime type information
     TypeName("zoneToCell");
 
+
     // Constructors
 
         //- Construct from components
@@ -108,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/cellZoneSources/setToCellZone/setToCellZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,52 @@ Class
     Foam::setToCellZone
 
 Description
-    A topoSetSource to select cells based on usage in a cellSet.
+    A \c topoSetSource to convert a \c cellSet
+    to a \c cellZone (and associated \c cellSet).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type     | Location
-        set         | The cell set name                     | yes |
+      input     | cellSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 1  | cellSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 2  | cellZone | $FOAM_CASE/constant/polyMesh/cellZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        cellZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      setToCellZone;
+        set         <cellSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of cellZone                    | word |  yes  | -
+      type       | Type name: cellZoneSet              | word |  yes  | -
+      action     | Action applied on cells - see below | word |  yes  | -
+      source     | Source name: setToCellZone          | word |  yes  | -
+      set        | Name of input cellSet               | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new cellZone from selected cells of a cellSet
+      add      | Add selected cells of a cellSet into this cellZone
+      subtract | Remove selected cells of a cellSet from this cellZone
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+
 SourceFiles
     setToCellZone.C
 
@@ -59,19 +97,21 @@ class setToCellZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
 
-        //- Name of set to use
+        //- Name of cellSet to use
         word setName_;
 
+
 public:
 
     //- Runtime type information
     TypeName("setToCellZone");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/faceSources/boundaryToFace/boundaryToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,10 +28,48 @@ Class
     Foam::boundaryToFace
 
 Description
-    A topoSetFaceSource to select all external (boundary) faces.
+    A \c topoSetFaceSource to select faces on all external boundaries.
 
-    \heading Dictionary parameters
+    Operands:
-    None
+    \table
+      Operand   | Type    | Location
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+    \endtable
+
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      boundaryToFace;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of faceSet                      | word |  yes  | -
+      type       | Type name: faceSet                   | word |  yes  | -
+      action     | Action applied on faces - see below  | word |  yes  | -
+      source     | Source name: boundaryToFace          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+    - Foam::patchToFace
 
 SourceFiles
     boundaryToFace.C
@@ -56,7 +94,7 @@ class boundaryToFace
 :
     public topoSetFaceSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -72,6 +110,7 @@ public:
     //- Runtime type information
     TypeName("boundaryToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -95,7 +134,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/boxToFace/boxToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,20 +28,80 @@ Class
     Foam::boxToFace
 
 Description
-    A topoSetFaceSource to select faces based on face centres inside box.
+    A \c topoSetFaceSource to select all faces
+    whose face centre inside given bounding box(es).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        boxes       | Multiple bounding boxes               | partly   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        box         | A single bounding box                 | partly   |
-        min         | Minimum point for a single box        | partly   |
-        max         | Maximum point for a single box        | partly   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      boxToFace;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        boxes
+        (
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-1
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-2
+            ...
+        );
+
+        // Option-2
+        box (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>);
+
+        // Option-3
+        min (<minX> <minY> <minZ>);
+        max (<maxX> <maxY> <maxZ>);
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: boxToFace              | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected cells
+      add      | Add selected cells into this faceSet
+      subtract | Remove selected cells from this faceSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type       | Req'd  | Dflt
+      boxes    | Multiple bounding boxes        | vectorList | cond'l | -
+      box      | A single bounding box          | vector     | cond'l | -
+      min      | Minimum point for a single box | vector     | cond'l | -
+      max      | Maximum point for a single box | vector     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "boxes", "box" or a "min/max" pair
+    The order of precedence among the conditional mandatory entries from the
-    (compatibility with searchable box) - highest to lowest precedence.
+    highest to the lowest is \c boxes, \c box or a \c min-max pair
+    (compatibility with \c searchableBox).
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
 
 SourceFiles
     boxToFace.C
@@ -67,7 +127,7 @@ class boxToFace
 :
     public topoSetFaceSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -86,6 +146,7 @@ public:
     //- Runtime type information
     TypeName("boxToFace");
 
+
     // Constructors
 
         //- Construct from components, copying bounding boxes

src/meshTools/sets/faceSources/cellToFace/cellToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,22 +28,81 @@ Class
     Foam::cellToFace
 
 Description
-    A topoSetFaceSource to select a faceSet from a cellSet.
+    A \c topoSetFaceSource to select all the faces from given \c cellSet(s).
 
-    Either use 'all' cell faces, or only faces that have cells
+    Operands:
-    on 'both' sides.
-
-    \heading Dictionary parameters
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type       | Location
-        sets        | The cellSet names to use          | possibly |
+      input     | cellSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The cellSet name to use           | possibly |
+      output    | faceSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection (all/both)              | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      cellToFace;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <cellSetName1>
+            <cellSetName2>
+            ...
+        );
+
+        // Option-2
+        set <cellSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: cellToFace             | word |  yes  | -
+      option     | Selection type - see below          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected cells of cellSet(s)
+      add      | Add selected faces of cellSet(s) into this faceSet
+      subtract | Remove selected faces of cellSet(s) from this faceSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      all     | All faces of cells in the cellSet
+      both    | Faces where both neighbours are in the cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type     | Req'd  | Dflt
+      sets     | Names of input cellSets        | wordList | cond'l | -
+      set      | Name of input cellSet          | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
-    When picking up coupled faces, it uses cells on neighbouring processors.
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
 
 SourceFiles
     cellToFace.C
@@ -80,15 +139,17 @@ public:
 
 private:
 
+    // Private Data
+
         //- Add usage string
         static addToUsageTable usage_;
 
         static const Enum<cellAction> cellActionNames_;
 
-        //- Names of sets to use
+        //- Names of cellSets to use
         wordList names_;
 
-        //- Option
+        //- Selection type
         cellAction option_;
 
 
@@ -103,6 +164,7 @@ public:
     //- Runtime type information
     TypeName("cellToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -131,7 +193,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/cylinderAnnulusToFace/cylinderAnnulusToFace.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -121,7 +121,15 @@ Foam::cylinderAnnulusToFace::cylinderAnnulusToFace
     point2_(point2),
     radius_(radius),
     innerRadius_(innerRadius)
-{}
+{
+    if (innerRadius_ > radius_)
+    {
+        FatalErrorInFunction
+            << "inner radius = " << innerRadius_ << "cannot be larger than "
+            << "outer radius = " << radius_
+            << exit(FatalIOError);
+    }
+}
 
 
 Foam::cylinderAnnulusToFace::cylinderAnnulusToFace
@@ -135,8 +143,8 @@ Foam::cylinderAnnulusToFace::cylinderAnnulusToFace
         mesh,
         dict.get<point>("p1"),
         dict.get<point>("p2"),
-        dict.get<scalar>("outerRadius"),
+        dict.getCheck<scalar>("outerRadius", scalarMinMax::ge(SMALL)),
-        dict.get<scalar>("innerRadius")
+        dict.getCheck<scalar>("innerRadius", scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/faceSources/cylinderAnnulusToFace/cylinderAnnulusToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,60 @@ Class
     Foam::cylinderAnnulusToFace
 
 Description
-    A topoSetFaceSource to select faces based on face centres inside a
+    A \c topoSetFaceSource to select all faces whose face
-    cylinder annulus.
+    centre inside a given bounding cylinder annulus.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        p1          | Coordinate of endpoint            | yes   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        p2          | Coordinate of endpoint            | yes   |
-        outerRadius | Cylinder outer radius             | yes   |
-        innerRadius | Cylinder inner radius             | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name           <name>;
+        type           faceSet;
+        action         <action>;
+
+        // Mandatory entries
+        source         cylinderAnnulusToFace;
+        p1             (<p1X> <p1Y> <p1Z>);
+        p2             (<p2X> <p2Y> <p2Z>);
+        outerRadius    <radius1>;
+
+        // Optional entries
+        innerRadius    <radius2>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: cylinderAnnulusToFace  | word |  yes  | -
+      p1          | Coordinate of one of the endpoints | vector |  yes  | -
+      p2          | Coordinate of the other endpoint   | vector |  yes  | -
+      outerRadius | Cylinder outer radius              | scalar |  yes  | -
+      innerRadius | Cylinder inner radius              | scalar |  no   | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+    - Foam::cylinderToFace
+
 SourceFiles
     cylinderAnnulusToFace.C
 
@@ -63,8 +105,7 @@ class cylinderAnnulusToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;

src/meshTools/sets/faceSources/cylinderToFace/cylinderToFace.C

@@ -110,7 +110,15 @@ Foam::cylinderToFace::cylinderToFace
     point2_(point2),
     radius_(radius),
     innerRadius_(innerRadius)
-{}
+{
+    if (innerRadius_ > radius_)
+    {
+        FatalErrorInFunction
+            << "inner radius = " << innerRadius_ << "cannot be larger than "
+            << "outer radius = " << radius_
+            << exit(FatalIOError);
+    }
+}
 
 
 Foam::cylinderToFace::cylinderToFace
@@ -124,8 +132,8 @@ Foam::cylinderToFace::cylinderToFace
         mesh,
         dict.get<point>("p1"),
         dict.get<point>("p2"),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(SMALL)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/faceSources/cylinderToFace/cylinderToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,60 @@ Class
     Foam::cylinderToFace
 
 Description
-    A topoSetFaceSource to select faces based on face centres inside a cylinder.
+    A \c topoSetFaceSource to select all faces whose face centre
+    inside a given bounding cylinder or cylinder annulus.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required | Default
+      Operand   | Type    | Location
-        p1          | Coordinate of endpoint            | yes   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        p2          | Coordinate of endpoint            | yes   |
-        radius      | Cylinder (outer) radius           | yes   |
-        innerRadius | Cylinder inner radius             | no    | 0
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name           <name>;
+        type           faceSet;
+        action         <action>;
+
+        // Mandatory entries
+        source         cylinderToFace;
+        p1             (<p1X> <p1Y> <p1Z>);
+        p2             (<p2X> <p2Y> <p2Z>);
+        radius         <radius1>;
+
+        // Optional entries
+        innerRadius    <radius2>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: cylinderToFace         | word |  yes  | -
+      p1          | Coordinate of one of the endpoints | vector |  yes  | -
+      p2          | Coordinate of the other endpoint   | vector |  yes  | -
+      radius      | Cylinder outer radius              | scalar |  yes  | -
+      innerRadius | Cylinder inner radius              | scalar |  no   | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+    - Foam::cylinderAnnulusToFace
+
 SourceFiles
     cylinderToFace.C
 
@@ -62,8 +105,7 @@ class cylinderToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;

src/meshTools/sets/faceSources/faceToFace/faceToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,73 @@ Class
     Foam::faceToFace
 
 Description
-    A topoSetFaceSource to select faces based on usage in another faceSet.
+    A \c topoSetFaceSource to select faces based on usage in another \c faceSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        sets        | The input faceSet names           | possibly |
+      input     | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The input faceSet name            | possibly |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      faceToFace;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <faceSetName0>
+            <faceSetName1>
+            ...
+        );
+
+        // Option-2
+        set     <faceSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: faceToFace             | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input faceSets    | wordList | cond'l | -
+      set      | Name of input faceSet      | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
 
 SourceFiles
     faceToFace.C
@@ -63,12 +119,12 @@ class faceToFace
 :
     public topoSetFaceSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
 
-        //- Names of sets to use
+        //- Names of faceSets to use
         wordList names_;
 
 
@@ -77,6 +133,7 @@ public:
     //- Runtime type information
     TypeName("faceToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -100,7 +157,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/labelToFace/labelToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,15 +28,56 @@ Class
     Foam::labelToFace
 
 Description
-    A topoSetFaceSource to select faces given explicitly provided face labels.
+    A \c topoSetFaceSource to select faces
+    based on explicitly given face labels.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        normal      | The normal for selecting faces    | yes   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        cos         | Tolerance angle (range -1, +1)    | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      labelToFace;
+        value
+        (
+            <faceLabel1>
+            <faceLabel2>
+            ...
+        );
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: labelToFace            | word |  yes  | -
+      value      | Input face labels                   | labelList | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+
 SourceFiles
     labelToFace.C
 
@@ -60,8 +101,7 @@ class labelToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -75,6 +115,7 @@ public:
     //- Runtime type information
     TypeName("labelToFace");
 
+
     // Constructors
 
         //- Construct from components, copying labels
@@ -101,7 +142,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/normalToFace/normalToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,15 +28,54 @@ Class
     Foam::normalToFace
 
 Description
-    A topoSetFaceSource to select faces based on normal.
+    A \c topoSetFaceSource to select faces whose surface normal aligned
+    with a given direction.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type    | Location
-        normal      | The normal for selecting faces    | yes   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        cos         | Tolerance angle (range -1, +1)    | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      normalToFace;
+        normal      (1 0 0);
+        cos         0.01;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: normalToFace           | word |  yes  | -
+      normal     | The surface normal direction        | vector | yes | -
+      cos        | Tolerance angle (range -1, +1), i.e. cosine of angle <!--
+               --> between the input normal and face normal | scalar | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+
 SourceFiles
     normalToFace.C
 
@@ -60,13 +99,12 @@ class normalToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-private:
 
         //- Add usage string
         static addToUsageTable usage_;
 
-        //- (unit)vector to compare to
+        //- The surface normal direction
         vector normal_;
 
         //- Tolerance (i.e. cos of angle between normal_ and faceNormal)
@@ -84,6 +122,7 @@ public:
     //- Runtime type information
     TypeName("normalToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -112,7 +151,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/patchToFace/patchToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,73 @@ Class
     Foam::patchToFace
 
 Description
-    A topoSetFaceSource to select faces based on usage in patches.
+    A \c topoSetFaceSource to select cells associated with given patch(es).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        patches     | The patch names or regexs             | possibly |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        patch       | The patch name or regex               | possibly |
-        name        | Older specification for 'patch'       | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      patchToFace;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        patches
+        (
+            <patchName1>
+            <patchName2>
+            ...
+        );
+
+        // Option-2
+        patch    <patchName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: patchToFace            | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description           | Type     | Req'd  | Dflt
+      patches  | Names of patches      | wordList | cond'l | -
+      patch    | Name of patch         | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "patches", "patch" or "name" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c patches, and \c patch.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+    - Foam::boundaryToFace
 
 SourceFiles
     patchToFace.C
@@ -65,8 +120,7 @@ class patchToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -85,6 +139,7 @@ public:
     //- Runtime type information
     TypeName("patchToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -108,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/pointToFace/pointToFace.C

@@ -67,6 +67,7 @@ Foam::topoSetSource::addToUsageTable Foam::pointToFace::usage_
     "    -two consecutive points (an edge) in the pointSet\n\n"
 );
 
+
 const Foam::Enum
 <
     Foam::pointToFace::pointAction

src/meshTools/sets/faceSources/pointToFace/pointToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2012 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,83 @@ Class
     Foam::pointToFace
 
 Description
-    A topoSetFaceSource to select faces based on use of points.
+    A \c topoSetFaceSource to select faces with any
+    point or any edge within a given \c pointSet(s).
 
-    \heading Dictionary parameters
+    Operands
     \table
-        Property    | Description                       | Required | Default
+      Operand   | Type        | Location
-        sets        | The pointSet names to use         | possibly |
+      input     | pointSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The pointSet name to use          | possibly |
+      output    | faceSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection type (all/any/edge)     | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      pointToFace;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <pointSetName1>
+            <pointSetName2>
+            ...
+        );
+
+        // Option-2
+        set   <pointSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: pointToFace            | word |  yes  | -
+      option     | Selection type - see below          | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      any     | Any point in the pointSet
+      edge    | Two consecutive points (an edge) in the pointSet
+      all     | All points in the pointSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input pointSets   | wordList | cond'l | -
+      set      | Name of input pointSet     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
 
 SourceFiles
     pointToFace.C
@@ -93,7 +158,7 @@ private:
 
     // Private Member Functions
 
-        //- Depending on face to cell option add to or delete from cellSet.
+        //- Depending on face to cell option add to or delete from faceSet.
         void combine(topoSet& set, const bool add, const word& setName) const;
 
 
@@ -102,6 +167,7 @@ public:
     //- Runtime type information
     TypeName("pointToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -130,7 +196,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/regionToFace/regionToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2012-2016 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,16 +28,54 @@ Class
     Foam::regionToFace
 
 Description
-    A topoSetFaceSource to select faces belonging to a topological connected
+    A \c topoSetFaceSource to select cells belonging to a topologically
-    region (that contains given point)
+    connected region (that contains given points).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type     | Location
-        set         | The face set name to use          | yes   |
+      input     | region   | $FOAM_CASE/constant/\{\<region\>, polyMesh\}
-        nearPoint   | The point on/near to the region   | yes   |
+      output    | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      regionToFace;
+        set         <faceSetName>;
+        nearPoint   <point>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: regionToFace           | word |  yes  | -
+      set        | Name of faceSet restricting search  | word |  yes  | -
+      nearPoint  | The point on/near to the region     | vector | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+
 SourceFiles
     regionToFace.C
 
@@ -62,7 +100,7 @@ class regionToFace
 :
     public topoSetFaceSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -88,11 +126,13 @@ class regionToFace
 
         void combine(topoSet& set, const bool add) const;
 
+
 public:
 
     //- Runtime type information
     TypeName("regionToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -121,7 +161,6 @@ public:
             const topoSetSource::setAction action,
             topoSet&
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/searchableSurfaceToFace/searchableSurfaceToFace.C

@@ -102,7 +102,7 @@ void Foam::searchableSurfaceToFace::combine(topoSet& set, const bool add) const
     s.getVolumeType(ctrs, volTypes);
 
     const label len = volTypes.size();
-    for (label elemi=0; elemi < len; ++elemi)
+    for (label elemi = 0; elemi < len; ++elemi)
     {
         if (volTypes[elemi] == volumeType::INSIDE)
         {

src/meshTools/sets/faceSources/searchableSurfaceToFace/searchableSurfaceToFace.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,56 @@ Class
     Foam::searchableSurfaceToFace
 
 Description
-    A topoSetFaceSource to select faces with centres within a
+    A \c topoSetFaceSource to select faces whose face
-    searchableSurface.
+    centre enclosed by a given \c searchableSurface.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type        | Location
-        surfaceType | The searchable surface type           | yes   |
+      input     | triSurface  | $FOAM_CASE/constant/triSurface/\<file\>
-        surfaceName | Name for the IOobject                 | no    | mesh-name
+      output    | faceSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        surface     | Same as 'surfaceType'                 | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      searchableSurfaceToFace;
+        surfaceType <surfaceTypeName>;
+
+        // Optional entries
+        surfaceName <surfaceName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: searchableSurfaceToFace | word |  yes | -
+      surfaceType | The searchable surface type        | word |  yes  | -
+      surfaceName | Name for the IOobject              | word | no | mesh-name
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+
 SourceFiles
     searchableSurfaceToFace.C
 

src/meshTools/sets/faceSources/sphereToFace/sphereToFace.C

@@ -113,8 +113,8 @@ Foam::sphereToFace::sphereToFace
     (
         mesh,
         dict.getCompat<vector>("origin", {{"centre", -1806}}),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(0)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/faceSources/sphereToFace/sphereToFace.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,57 @@ Class
     Foam::sphereToFace
 
 Description
-    A topoSetFaceSource to select faces based on faces centres inside sphere.
+    A \c topoSetFaceSource to select faces based
+    on face centres inside a given bounding sphere.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type    | Location
-        origin      | The origin (centre) of the sphere     | yes   |
+      output    | faceSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        radius      | The (outer) radius of sphere          | yes   |
-        innerRadius | The inner radius of sphere            | no    | 0
-        centre      | Alternative for 'origin'              | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      sphereToFace;
+        origin      (0 0 0);
+        radius      0.5;
+
+        // Optional entries
+        innerRadius 0;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: sphereToFace           | word |  yes  | -
+      origin     | The origin (centre) of the sphere   | vector | yes | -
+      radius     | The (outer) radius of sphere        | scalar | yes | -
+      innerRadius | The inner radius of sphere         | scalar | no  | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
+
 SourceFiles
     sphereToFace.C
 
@@ -61,8 +101,7 @@ class sphereToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -117,7 +156,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceSources/topoSetFaceSource/topoSetFaceSource.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,7 +27,11 @@ Class
     Foam::topoSetFaceSource
 
 Description
-    Base class of a topoSet source for selecting faces.
+    The \c topoSetFaceSource is a intermediate class
+    for handling \c topoSet sources for selecting faces.
+
+    The class is not an executable \c topoSet itself,
+    yet a provider for common entries to its derived \c topoSet.
 
 SourceFiles
     topoSetFaceSource.C

src/meshTools/sets/faceSources/zoneToFace/zoneToFace.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,73 @@ Class
     Foam::zoneToFace
 
 Description
-    A topoSetFaceSource to select faces based on one of more faceZones.
+    A \c topoSetFaceSource to convert \c faceZone(s) to a \c faceSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type        | Location
-        zones       | The face zone names or regexs         | possibly |
+      input     | faceZone(s) | $FOAM_CASE/constant/polyMesh/faceZones
-        zone        | The face zone name or regex           | possibly |
+      output    | faceSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        name        | Older specification for 'zone'        | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      zoneToFace;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        zones
+        (
+            <faceZoneName0>
+            <faceZoneName1>
+            ...
+        );
+
+        // Option-2
+        zone     <faceZoneName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceSet                     | word |  yes  | -
+      type       | Type name: faceSet                  | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: zoneToFace             | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceSet from selected faces
+      add      | Add selected faces into this faceSet
+      subtract | Remove selected faces from this faceSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      zones    | Names of input faceZones   | wordList | cond'l | -
+      zone     | Name of input faceZone     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "zones", "zone" or "name" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c zones, and \c zone.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetFaceSource
 
 SourceFiles
     zoneToFace.C
@@ -65,8 +120,7 @@ class zoneToFace
 :
     public topoSetFaceSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -85,6 +139,7 @@ public:
     //- Runtime type information
     TypeName("zoneToFace");
 
+
     // Constructors
 
         //- Construct from components
@@ -108,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/faceZoneSources/faceZoneToFaceZone/faceZoneToFaceZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,51 @@ Class
     Foam::faceZoneToFaceZone
 
 Description
-    A topoSetSource to select faces based on usage in another faceSet.
+    A \c topoSetSource to select faces of a given \c faceZone.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                        | Required  | Default
+      Operand   | Type     | Location
-        zone        | Name of input face zone (no regex) | yes   |
+      input     | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 1  | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 2  | faceZone | $FOAM_CASE/constant/polyMesh/faceZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      faceZoneToFaceZone;
+        zone        <faceZoneName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceZone                    | word |  yes  | -
+      type       | Type name: faceZoneSet              | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: faceZoneToFaceZone     | word |  yes  | -
+      zone       | Name of input faceZone              | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceZone from selected faces of a faceZone
+      add      | Add selected faces of a faceZone into this faceZone
+      subtract | Remove selected faces of a faceZone from this faceZone
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+
 SourceFiles
     faceZoneToFaceZone.C
 
@@ -59,7 +96,7 @@ class faceZoneToFaceZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -67,11 +104,13 @@ class faceZoneToFaceZone
         //- Name of set to use
         word setName_;
 
+
 public:
 
     //- Runtime type information
     TypeName("faceZoneToFaceZone");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/faceZoneSources/planeToFaceZone/planeToFaceZone.C

@@ -0,0 +1,413 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2020 OpenFOAM Foundation
+    Copyright (C) 2020 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+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/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "planeToFaceZone.H"
+#include "polyMesh.H"
+#include "faceZoneSet.H"
+#include "uindirectPrimitivePatch.H"
+#include "PatchTools.H"
+#include "syncTools.H"
+#include "addToRunTimeSelectionTable.H"
+
+// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    defineTypeNameAndDebug(planeToFaceZone, 0);
+    addToRunTimeSelectionTable(topoSetSource, planeToFaceZone, word);
+    addToRunTimeSelectionTable(topoSetSource, planeToFaceZone, istream);
+}
+
+
+Foam::topoSetSource::addToUsageTable Foam::planeToFaceZone::usage_
+(
+    planeToFaceZone::typeName,
+    "\n    Usage: planeToFaceZone (px py pz) (nx ny nz) include\n\n"
+    "    Select faces for which the adjacent cell centres lie on opposite "
+    " of a plane\n\n"
+);
+
+
+const Foam::Enum
+<
+    Foam::planeToFaceZone::faceZoneAction
+>
+Foam::planeToFaceZone::faceZoneActionNames_
+({
+    { faceZoneAction::ALL, "all" },
+    { faceZoneAction::CLOSEST, "closest" },
+});
+
+
+// * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
+
+void Foam::planeToFaceZone::combine(faceZoneSet& fzSet, const bool add) const
+{
+    // Mark all cells with centres above the plane
+    boolList cellIsAbovePlane(mesh_.nCells());
+    forAll(mesh_.cells(), celli)
+    {
+        cellIsAbovePlane[celli] =
+            ((mesh_.cellCentres()[celli] - point_) & normal_) > 0;
+    }
+
+    // Mark all faces that sit between cells above and below the plane
+    boolList faceIsOnPlane(mesh_.nFaces());
+    forAll(mesh_.faceNeighbour(), facei)
+    {
+        faceIsOnPlane[facei] =
+            cellIsAbovePlane[mesh_.faceOwner()[facei]]
+         != cellIsAbovePlane[mesh_.faceNeighbour()[facei]];
+    }
+    forAll(mesh_.boundaryMesh(), patchi)
+    {
+        const polyPatch& patch = mesh_.boundaryMesh()[patchi];
+        forAll(patch, patchFacei)
+        {
+            const label facei = patch.start() + patchFacei;
+            faceIsOnPlane[facei] =
+                patch.coupled() && cellIsAbovePlane[mesh_.faceOwner()[facei]];
+        }
+    }
+    syncTools::syncFaceList(mesh_, faceIsOnPlane, notEqOp<bool>());
+
+    // Convert marked faces to a list of indices
+    labelList newSetFaces(findIndices(faceIsOnPlane, true));
+
+    // If constructing a single contiguous set, remove all faces except those
+    // connected to the contiguous region closest to the specified point
+    if (option_ == faceZoneAction::CLOSEST)
+    {
+        // Step 1: Get locally contiguous regions for the new face set and the
+        // total number of regions across all processors.
+        labelList newSetFaceRegions(newSetFaces.size(), -1);
+        label nRegions = -1;
+        {
+            // Create a patch of the set faces
+            const uindirectPrimitivePatch newSetPatch
+            (
+                UIndirectList<face>(mesh_.faces(), newSetFaces),
+                mesh_.points()
+            );
+
+            // Get the region ID-s and store the total number of regions on
+            // each processor
+            labelList procNRegions(Pstream::nProcs(), -1);
+            procNRegions[Pstream::myProcNo()] =
+                PatchTools::markZones
+                (
+                    newSetPatch,
+                    boolList(newSetPatch.nEdges(), false),
+                    newSetFaceRegions
+                );
+            Pstream::gatherList(procNRegions);
+            Pstream::scatterList(procNRegions);
+
+            // Cumulative sum the number of regions on each processor to get an
+            // offset which makes the local region ID-s globally unique
+            labelList procRegionOffset(Pstream::nProcs(), 0);
+            for (label proci = 1; proci < Pstream::nProcs(); ++ proci)
+            {
+                procRegionOffset[proci] +=
+                    procRegionOffset[proci - 1]
+                  + procNRegions[proci - 1];
+            }
+
+            // Apply the offset
+            forAll(newSetFaces, newSetFacei)
+            {
+                newSetFaceRegions[newSetFacei] +=
+                    procRegionOffset[Pstream::myProcNo()];
+            }
+
+            // Store the total number of regions across all processors
+            nRegions = procRegionOffset.last() + procNRegions.last();
+        }
+
+        // Step 2: Create a region map which combines regions which are
+        // connected across coupled interfaces
+        labelList regionMap(identity(nRegions));
+        {
+            // Put region labels on connected boundary edges and synchronise to
+            // create a list of all regions connected to a given edge
+            labelListList meshEdgeRegions(mesh_.nEdges(), labelList());
+            forAll(newSetFaces, newSetFacei)
+            {
+                const label facei = newSetFaces[newSetFacei];
+                const label regioni = newSetFaceRegions[newSetFacei];
+                forAll(mesh_.faceEdges()[facei], faceEdgei)
+                {
+                    const label edgei = mesh_.faceEdges()[facei][faceEdgei];
+                    meshEdgeRegions[edgei] = labelList(1, regioni);
+                }
+            }
+            syncTools::syncEdgeList
+            (
+                mesh_,
+                meshEdgeRegions,
+                globalMeshData::ListPlusEqOp<labelList>(),
+                labelList()
+            );
+
+            // Combine edge regions to create a list of what regions a given
+            // region is connected to
+            List<labelHashSet> regionRegions(nRegions);
+            forAll(newSetFaces, newSetFacei)
+            {
+                const label facei = newSetFaces[newSetFacei];
+                const label regioni = newSetFaceRegions[newSetFacei];
+                forAll(mesh_.faceEdges()[facei], faceEdgei)
+                {
+                    const label edgei = mesh_.faceEdges()[facei][faceEdgei];
+                    forAll(meshEdgeRegions[edgei], edgeRegioni)
+                    {
+                        if (meshEdgeRegions[edgei][edgeRegioni] != regioni)
+                        {
+                            regionRegions[regioni].insert
+                            (
+                                meshEdgeRegions[edgei][edgeRegioni]
+                            );
+                        }
+                    }
+                }
+            }
+            Pstream::listCombineGather(regionRegions, plusEqOp<labelHashSet>());
+            Pstream::listCombineScatter(regionRegions);
+
+            // Collapse the region connections into a map between each region
+            // and the lowest numbered region that it connects to
+            forAll(regionRegions, regioni)
+            {
+                forAllConstIter(labelHashSet, regionRegions[regioni], iter)
+                {
+                    regionMap[iter.key()] =
+                        min(regionMap[iter.key()], regionMap[regioni]);
+                }
+            }
+        }
+
+        // Step 3: Combine connected regions
+        labelList regionNFaces;
+        {
+            // Remove duplicates from the region map
+            label regioni0 = 0;
+            forAll(regionMap, regioni)
+            {
+                if (regionMap[regioni] > regioni0)
+                {
+                    ++ regioni0;
+                    regionMap[regioni] = regioni0;
+                }
+            }
+
+            // Recompute the number of regions
+            nRegions = regioni0 + 1;
+
+            // Renumber the face region ID-s
+            newSetFaceRegions =
+                IndirectList<label>(regionMap, newSetFaceRegions);
+
+            // Report the final number and size of the regions
+            regionNFaces = labelList(nRegions, 0);
+            forAll(newSetFaces, newSetFacei)
+            {
+                regionNFaces[newSetFaceRegions[newSetFacei]] ++;
+            }
+            Pstream::listCombineGather(regionNFaces, plusEqOp<label>());
+            Pstream::listCombineScatter(regionNFaces);
+            Info<< "    Found " << nRegions << " contiguous regions with "
+                << regionNFaces << " faces" << endl;
+        }
+
+        // Step 4: Choose the closest region to output
+        label selectedRegioni = -1;
+        {
+            // Compute the region centres
+            scalarField regionMagAreas(nRegions, 0);
+            pointField regionCentres(nRegions, Zero);
+            forAll(newSetFaces, newSetFacei)
+            {
+                const label facei = newSetFaces[newSetFacei];
+                const label regioni = newSetFaceRegions[newSetFacei];
+
+                const vector& a = mesh_.faceAreas()[facei];
+                const point& c = mesh_.faceCentres()[facei];
+
+                regionMagAreas[regioni] += mag(a);
+                regionCentres[regioni] += mag(a)*c;
+            }
+            Pstream::listCombineGather(regionMagAreas, plusEqOp<scalar>());
+            Pstream::listCombineGather(regionCentres, plusEqOp<point>());
+            Pstream::listCombineScatter(regionMagAreas);
+            Pstream::listCombineScatter(regionCentres);
+            regionCentres /= regionMagAreas;
+
+            // Find the region centroid closest to the reference point
+            selectedRegioni =
+                returnReduce
+                (
+                    findMin(mag(regionCentres - point_)()),
+                    minOp<label>()
+                );
+
+            // Report the selection
+            Info<< "    Selecting region " << selectedRegioni << " with "
+                << regionNFaces[selectedRegioni]
+                << " faces as the closest to point " << point_ << endl;
+        }
+
+        // Step 5: Remove any faces from the set list not in the selected region
+        {
+            // Remove faces from the list by shuffling up and resizing
+            label newSetFacei0 = 0;
+            forAll(newSetFaces, newSetFacei)
+            {
+                newSetFaces[newSetFacei0] = newSetFaces[newSetFacei];
+
+                if (newSetFaceRegions[newSetFacei] == selectedRegioni)
+                {
+                    ++ newSetFacei0;
+                }
+            }
+            newSetFaces.resize(newSetFacei0);
+        }
+    }
+
+    // Modify the face zone set
+    DynamicList<label> newAddressing;
+    DynamicList<bool> newFlipMap;
+    if (add)
+    {
+        // Start from copy
+        newAddressing = DynamicList<label>(fzSet.addressing());
+        newFlipMap = DynamicList<bool>(fzSet.flipMap());
+
+        // Add anything from the new set that is not already in the zone set
+        forAll(newSetFaces, newSetFacei)
+        {
+            const label facei = newSetFaces[newSetFacei];
+
+            if (!fzSet.found(facei))
+            {
+                newAddressing.append(facei);
+                newFlipMap.append(cellIsAbovePlane[mesh_.faceOwner()[facei]]);
+            }
+        }
+    }
+    else
+    {
+        // Start from empty
+        newAddressing = DynamicList<label>(fzSet.addressing().size());
+        newFlipMap = DynamicList<bool>(fzSet.flipMap().size());
+
+        // Add everything from the zone set that is not also in the new set
+        labelHashSet newSet(newSetFaces);
+        forAll(fzSet.addressing(), i)
+        {
+            const label facei = fzSet.addressing()[i];
+
+            if (!newSet.found(facei))
+            {
+                newAddressing.append(facei);
+                newFlipMap.append(cellIsAbovePlane[mesh_.faceOwner()[facei]]);
+            }
+        }
+    }
+    fzSet.addressing().transfer(newAddressing);
+    fzSet.flipMap().transfer(newFlipMap);
+    fzSet.updateSet();
+}
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+Foam::planeToFaceZone::planeToFaceZone
+(
+    const polyMesh& mesh,
+    const dictionary& dict
+)
+:
+    topoSetSource(mesh),
+    point_(dict.get<vector>("point")),
+    normal_(dict.get<vector>("normal")),
+    option_
+    (
+        faceZoneActionNames_.getOrDefault("option", dict, faceZoneAction::ALL)
+    )
+{}
+
+
+Foam::planeToFaceZone::planeToFaceZone
+(
+    const polyMesh& mesh,
+    Istream& is
+)
+:
+    topoSetSource(mesh),
+    point_(checkIs(is)),
+    normal_(checkIs(is)),
+    option_(faceZoneActionNames_.read(checkIs(is)))
+{}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+void Foam::planeToFaceZone::applyToSet
+(
+    const topoSetSource::setAction action,
+    topoSet& set
+) const
+{
+    if (!isA<faceZoneSet>(set))
+    {
+        WarningInFunction
+            << "Operation only allowed on a faceZoneSet." << endl;
+    }
+    else
+    {
+        faceZoneSet& fzSet = refCast<faceZoneSet>(set);
+
+        if ((action == topoSetSource::NEW) || (action == topoSetSource::ADD))
+        {
+            Info<< "    Adding faces which form a plane at " << point_
+                << " with normal " << normal_ << endl;
+
+            combine(fzSet, true);
+        }
+        else if (action == topoSetSource::DELETE)
+        {
+            Info<< "    Removing faces which form a plane at " << point_
+                << " with normal " << normal_ << endl;
+
+            combine(fzSet, false);
+        }
+    }
+}
+
+
+// ************************************************************************* //

src/meshTools/sets/faceZoneSources/searchableSurfaceToFaceZone/searchableSurfaceToFaceZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2012 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,56 @@ Class
     Foam::searchableSurfaceToFaceZone
 
 Description
-    A topoSetSource to select faces based on intersection (of cell-cell
+    A \c topoSetSource to select all faces whose cell-cell centre vector
-    vector) with a surface.
+    intersects with a given \c searchableSurface.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type       | Location
-        surfaceType | The searchable surface type           | yes   |
+      input     | triSurface | $FOAM_CASE/constant/triSurface/\<file\>
-        surfaceName | Name for the IOobject                 | no    | mesh-name
+      output 1  | faceSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        surface     | Same as 'surfaceType'                 | no    |
+      output 2  | faceZone   | $FOAM_CASE/constant/polyMesh/faceZones
-        name        | Older specification for 'surfaceName' | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      searchableSurfaceToFaceZone;
+        surfaceType <surfaceTypeName>;
+
+        // Optional entries
+        surfaceName <surfaceName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of faceZone                     | word |  yes  | -
+      type       | Type name: faceZone                  | word |  yes  | -
+      action     | Action applied on faces - see below  | word |  yes  | -
+      source     | Source name: searchableSurfaceToFaceZone | word | yes | -
+      surfaceType | The searchable surface type        | word |  yes | -
+      surfaceName | Name for the IOobject              | word | no   | mesh-name
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceZone from selected faces
+      add      | Add selected faces into this faceZone
+      subtract | Remove selected faces from this faceZone
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+
 SourceFiles
     searchableSurfaceToFaceZone.C
 
@@ -65,7 +103,7 @@ class searchableSurfaceToFaceZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -91,6 +129,7 @@ public:
     //- Runtime type information
     TypeName("searchableSurfaceToFaceZone");
 
+
     // Constructors
 
         //- Construct surface-type from dictionary

src/meshTools/sets/faceZoneSources/setAndNormalToFaceZone/setAndNormalToFaceZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2013 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,16 +28,50 @@ Class
     Foam::setAndNormalToFaceZone
 
 Description
-    A topoSetSource to select faces based on usage in a faceSet, where the
+    A \c topoSetSource to select faces based on usage in a \c faceSet,
-    normal vector is used to orient the faces.
+    where the normal vector is used to orient the faces.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type     | Location
-        faceSet     | Name of input faceSet             | yes   |
+      input     | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        normal      | The normal vector for orientation | yes   |
+      output    | faceZone | $FOAM_CASE/constant/polyMesh/faceZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      setAndNormalToFaceZone;
+        faceSet     <faceSetName>;
+        normal      (1 0 0);
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceZoneSet                 | word |  yes  | -
+      type       | Type name: faceZoneSet              | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: setAndNormalToFaceZone | word |  yes  | -
+      faceSet    | Name of input faceSet               | word |  yes  | -
+      normal     | The normal vector for orientation   | vector | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceZoneSet from selected faces
+      add      | Add selected faces into this faceZoneSet
+      subtract | Remove selected faces from this faceZoneSet
+    \endverbatim
+
 SourceFiles
     setAndNormalToFaceZone.C
 
@@ -61,7 +95,7 @@ class setAndNormalToFaceZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;

src/meshTools/sets/faceZoneSources/setToFaceZone/setToFaceZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,20 +28,57 @@ Class
     Foam::setToFaceZone
 
 Description
-    A topoSetSource to select faces based on usage in a faceSet.
+    A \c topoSetSource to convert a \c faceSet
-    Sets flipMap to true.
+    to a \c faceZone (and associated \c faceSet).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type     | Location
-        faceSet     | Name of input faceSet                 | yes   |
+      input     | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 1  | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 2  | faceZone | $FOAM_CASE/constant/polyMesh/faceZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      setToFaceZone;
+        faceSet     <faceSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceZone                    | word |  yes  | -
+      type       | Type name: faceZoneSet              | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: setToFaceZone          | word |  yes  | -
+      faceSet    | Name of input faceSet               | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceZone from selected faces of a faceSet
+      add      | Add selected faces of a faceSet into this faceZone
+      subtract | Remove selected faces of a faceSet from this faceZone
+    \endverbatim
+
 Note
-    The use of keyword \c faceSet is consistent with the setsToFaceZone,
+    The use of keyword \c faceSet is consistent with the \c setsToFaceZone,
-    but inconsistent with setToCellZone and setToPointZone.
+    but inconsistent with \c setToCellZone and \c setToPointZone.
     Both of which use \c set instead.
 
+See also
+    - Foam::topoSetSource
+
 SourceFiles
     setToFaceZone.C
 
@@ -65,7 +102,7 @@ class setToFaceZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -73,11 +110,13 @@ class setToFaceZone
         //- Name of set to use
         word setName_;
 
+
 public:
 
     //- Runtime type information
     TypeName("setToFaceZone");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/faceZoneSources/setsToFaceZone/setsToFaceZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2013 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,16 +28,59 @@ Class
     Foam::setsToFaceZone
 
 Description
-    A topoSetSource to select faces based on usage in a faceSet and cellSet
+    A \c topoSetSource to select all faces in a given \c faceSet,
+    which are oriented in slave cells of a given \c cellSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type     | Location
-        cellSet     | Name of input cellSet                 | yes   |
+      input 1   | faceSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        faceSet     | Name of input faceSet                 | yes   |
+      input 2   | cellSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        flip        | Force flip of faces                   | no    | false
+      output    | faceZone | $FOAM_CASE/constant/polyMesh/faceZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        faceZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      setToFaceZone;
+        faceSet     <faceSetName>;
+        cellSet     <cellSetName>;
+
+        // Optional entries
+        flip        false;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                         | Type | Req'd | Dflt
+      name       | Name of faceZone                    | word |  yes  | -
+      type       | Type name: faceZoneSet              | word |  yes  | -
+      action     | Action applied on faces - see below | word |  yes  | -
+      source     | Source name: setsToFaceZone         | word |  yes  | -
+      faceSet    | Name of input faceSet               | word |  yes  | -
+      cellSet    | Name of input cellSet containing the slave cells <!--
+                                                   --> | word |  yes  | -
+      flip       | Flag to select master/slave cells   | bool |  no   | false
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new faceZone from selected faces
+      add      | Add selected faces of a faceZoneSet into this faceZone
+      subtract | Remove selected faces of a faceZoneSet from this faceZone
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+
 SourceFiles
     setsToFaceZone.C
 
@@ -61,7 +104,7 @@ class setsToFaceZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -75,11 +118,13 @@ class setsToFaceZone
         //- Whether cellSet is slave cells or master cells
         const bool flip_;
 
+
 public:
 
     //- Runtime type information
     TypeName("setsToFaceZone");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/pointSources/boxToPoint/boxToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,20 +28,80 @@ Class
     Foam::boxToPoint
 
 Description
-    A topoSetPointSource to select points based on whether they are inside box.
+    A \c topoSetPointSource to select all points based
+    on whether they are inside given bounding box(es).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type     | Location
-        boxes       | Multiple bounding boxes               | partly   |
+      output    | pointSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        box         | A single bounding box                 | partly   |
-        min         | Minimum point for a single box        | partly   |
-        max         | Maximum point for a single box        | partly   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      boxToPoint;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        boxes
+        (
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-1
+            (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>) // box-2
+            ...
+        );
+
+        // Option-2
+        box (<minX> <minY> <minZ>) (<maxX> <maxY> <maxZ>);
+
+        // Option-3
+        min (<minX> <minY> <minZ>);
+        max (<maxX> <maxY> <maxZ>);
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: boxToPoint              | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type       | Req'd  | Dflt
+      boxes    | Multiple bounding boxes        | vectorList | cond'l | -
+      box      | A single bounding box          | vector     | cond'l | -
+      min      | Minimum point for a single box | vector     | cond'l | -
+      max      | Maximum point for a single box | vector     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "boxes", "box" or a "min/max" pair
+    The order of precedence among the conditional mandatory entries from the
-    (compatibility with searchable box) - highest to lowest precedence.
+    highest to the lowest is \c boxes, \c box or a \c min-max pair
+    (compatibility with \c searchableBox).
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
 
 SourceFiles
     boxToPoint.C
@@ -67,8 +127,7 @@ class boxToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -87,6 +146,7 @@ public:
     //- Runtime type information
     TypeName("boxToPoint");
 
+
     // Constructors
 
         //- Construct from components, copying bounding boxes
@@ -113,7 +173,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/cellToPoint/cellToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,80 @@ Class
     Foam::cellToPoint
 
 Description
-    A topoSetPointSource to select points based on usage in cells.
+    A \c topoSetPointSource to select all the points from given \c cellSet(s).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type       | Location
-        sets        | The cellSet names to use          | possibly |
+      input     | cellSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The cellSet name to use           | possibly |
+      output    | pointSet   | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection type (all)              | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      cellToPoint;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <pointSetName1>
+            <pointSetName2>
+            ...
+        );
+
+        // Option-2
+        set <pointSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: cellToPoint             | word |  yes  | -
+      option     | Selection type - see below           | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      all      | Select all points of cells in the cellSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                    | Type     | Req'd  | Dflt
+      sets     | Names of input cellSets        | wordList | cond'l | -
+      set      | Name of input cellSet          | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
 
 SourceFiles
     cellToPoint.C
@@ -73,8 +135,11 @@ public:
             ALL
         };
 
+
 private:
 
+    // Private Data
+
         //- Add usage string
         static addToUsageTable usage_;
 
@@ -89,7 +154,6 @@ private:
 
     // Private Member Functions
 
-        //- Depending on face to cell option add to or delete from cellSet.
         void combine(topoSet& set, const bool add, const word& setName) const;
 
 
@@ -98,6 +162,7 @@ public:
     //- Runtime type information
     TypeName("cellToPoint");
 
+
     // Constructors
 
         //- Construct from components
@@ -126,7 +191,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/cylinderToPoint/cylinderToPoint.C

@@ -124,8 +124,8 @@ Foam::cylinderToPoint::cylinderToPoint
         mesh,
         dict.get<point>("p1"),
         dict.get<point>("p2"),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(0)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/pointSources/cylinderToPoint/cylinderToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2017 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,59 @@ Class
     Foam::cylinderToPoint
 
 Description
-    A topoSetPointSource to select points inside a cylinder.
+    A \c topoSetPointSource to select all points which are
+    inside a given bounding cylinder or cylinder annulus.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required | Default
+      Operand   | Type     | Location
-        p1          | Coordinate of endpoint            | yes   |
+      output    | pointSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        p2          | Coordinate of endpoint            | yes   |
-        radius      | Cylinder (outer) radius           | yes   |
-        innerRadius | Cylinder inner radius             | no    | 0
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name           <name>;
+        type           pointSet;
+        action         <action>;
+
+        // Mandatory entries
+        source         cylinderToPoint;
+        p1             (<p1X> <p1Y> <p1Z>);
+        p2             (<p2X> <p2Y> <p2Z>);
+        radius         <radius1>;
+
+        // Optional entries
+        innerRadius    <radius2>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd   | Dflt
+      name       | Name of pointSet                     | word |  yes    | -
+      type       | Type name: pointSet                  | word |  yes    | -
+      action     | Action applied on points - see below | word |  yes    | -
+      source     | Source name: cylinderToPoint         | word |  yes    | -
+      p1          | Coordinate of one of the endpoints  | vector |  yes  | -
+      p2          | Coordinate of the other endpoint    | vector |  yes  | -
+      radius      | Cylinder outer radius               | scalar |  yes  | -
+      innerRadius | Cylinder inner radius               | scalar |  no   | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     cylinderToPoint.C
 
@@ -62,8 +104,7 @@ class cylinderToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;

src/meshTools/sets/pointSources/faceToPoint/faceToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,81 @@ Class
     Foam::faceToPoint
 
 Description
-    A topoSetPointSource to select points based on usage in faces.
+    A \c topoSetPointSource to select all
+    points based on usage in given \c faceSet(s).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required | Default
+      Operand   | Type       | Location
-        sets        | The faceSet names to use          | possibly |
+      input     | faceSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The faceSet name to use           | possibly |
+      output    | pointSet   | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        option      | Selection type (all)              | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      faceToPoint;
+        option      <option>;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <faceSetName0>
+            <faceSetName1>
+            ...
+        );
+
+        // Option-2
+        set     <faceSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: faceToPoint             | word |  yes  | -
+      option     | Selection type - see below           | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+    Options for the \c option entry:
+    \verbatim
+      all       | Select all points of faces in the faceSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input faceSets    | wordList | cond'l | -
+      set      | Name of input faceSet      | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
 
 SourceFiles
     faceToPoint.C
@@ -73,8 +136,11 @@ public:
             ALL
         };
 
+
 private:
 
+    // Private Data
+
         //- Add usage string
         static addToUsageTable usage_;
 
@@ -89,7 +155,6 @@ private:
 
     // Private Member Functions
 
-        //- Depending on face to cell option add to or delete from cellSet.
         void combine(topoSet& set, const bool add, const word& setName) const;
 
 
@@ -98,6 +163,7 @@ public:
     //- Runtime type information
     TypeName("faceToPoint");
 
+
     // Constructors
 
         //- Construct from components
@@ -126,7 +192,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/labelToPoint/labelToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,56 @@ Class
     Foam::labelToPoint
 
 Description
-    A topoSetPointSource to select points given explicitly provided labels.
+    A \c topoSetPointSource to select points
+    based on explicitly given point labels.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type     | Location
-        value       | The point labels                  | yes   |
+      output    | pointSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      labelToPoint;
+        value
+        (
+            <pointLabel1>
+            <pointLabel2>
+            ...
+        );
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: labelToPoint            | word |  yes  | -
+      value      | Input point labels                   | labelList | yes | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     labelToPoint.C
 
@@ -59,8 +101,7 @@ class labelToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -74,6 +115,7 @@ public:
     //- Runtime type information
     TypeName("labelToPoint");
 
+
     // Constructors
 
         //- Construct from components, copying labels
@@ -100,7 +142,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/nearestToPoint/nearestToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,55 @@ Class
     Foam::nearestToPoint
 
 Description
-    A topoSetPointSource to select points nearest to points.
+    A \c topoSetPointSource to select points nearest to given points.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type     | Location
-        points      | List of selection points          | yes   |
+      output    | pointSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      nearestToPoint;
+        points
+        (
+            (<p1x> <p1y> <p1z>)
+            (<p2x> <p2y> <p2z>)
+            ...
+        );
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: nearestToPoint          | word |  yes  | -
+      points     | List of selection points      | vectorList  |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     nearestToPoint.C
 
@@ -59,8 +100,7 @@ class nearestToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -79,6 +119,7 @@ public:
     //- Runtime type information
     TypeName("nearestToPoint");
 
+
     // Constructors
 
         //- Construct from components, copying points
@@ -105,7 +146,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/pointToPoint/pointToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,17 +28,73 @@ Class
     Foam::pointToPoint
 
 Description
-    A topoSetPointSource to select the points from another pointSet.
+    A \c topoSetPointSource to select all points from given \c pointSet(s).
 
-    \heading Dictionary parameters
+    Operands
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type        | Location
-        sets        | The input pointSet names          | possibly |
+      input     | pointSet(s) | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        set         | The input pointSet name           | possibly |
+      output    | pointSet    | $FOAM_CASE/constant/polyMesh/sets/\<set\>
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      pointToPoint;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        sets
+        (
+            <pointSetName1>
+            <pointSetName2>
+            ...
+        );
+
+        // Option-2
+        set   <pointSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                          | Type | Req'd | Dflt
+      name       | Name of pointSet                     | word |  yes  | -
+      type       | Type name: pointSet                  | word |  yes  | -
+      action     | Action applied on points - see below | word |  yes  | -
+      source     | Source name: pointToPoint            | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      sets     | Names of input pointSets   | wordList | cond'l | -
+      set      | Name of input pointSet     | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "sets" or "set" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c sets, and \c set.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
 
 SourceFiles
     pointToPoint.C
@@ -63,7 +119,7 @@ class pointToPoint
 :
     public topoSetPointSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -77,6 +133,7 @@ public:
     //- Runtime type information
     TypeName("pointToPoint");
 
+
     // Constructors
 
         //- Construct from components
@@ -100,7 +157,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/searchableSurfaceToPoint/searchableSurfaceToPoint.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,16 +27,56 @@ Class
     Foam::searchableSurfaceToPoint
 
 Description
-    A topoSetPointSource to select mesh points within a searchableSurface.
+    A \c topoSetPointSource to select points which are
+    centre enclosed by a given \c searchableSurface.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type       | Location
-        surfaceType | The searchable surface type           | yes   |
+      input     | triSurface | $FOAM_CASE/constant/triSurface/\<file\>
-        surfaceName | Name for the IOobject                 | no    | mesh-name
+      output    | pointSet   | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        surface     | Same as 'surfaceType'                 | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      searchableSurfaceToPoint;
+        surfaceType <surfaceTypeName>;
+
+        // Optional entries
+        surfaceName <surfaceName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                           | Type | Req'd | Dflt
+      name       | Name of pointSet                      | word |  yes  | -
+      type       | Type name: pointSet                   | word |  yes  | -
+      action     | Action applied on points - see below  | word |  yes  | -
+      source     | Source name: searchableSurfaceToPoint | word |  yes | -
+      surfaceType | The searchable surface type          | word |  yes  | -
+      surfaceName | Name for the IOobject                | word | no | mesh-name
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     searchableSurfaceToPoint.C
 

src/meshTools/sets/pointSources/sphereToPoint/sphereToPoint.C

@@ -113,8 +113,8 @@ Foam::sphereToPoint::sphereToPoint
     (
         mesh,
         dict.getCompat<vector>("origin", {{"centre", -1806}}),
-        dict.get<scalar>("radius"),
+        dict.getCheck<scalar>("radius", scalarMinMax::ge(0)),
-        dict.getOrDefault<scalar>("innerRadius", 0)
+        dict.getCheckOrDefault<scalar>("innerRadius", 0, scalarMinMax::ge(0))
     )
 {}
 

src/meshTools/sets/pointSources/sphereToPoint/sphereToPoint.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,17 +27,57 @@ Class
     Foam::sphereToPoint
 
 Description
-    A topoSetPointSource to select based on mesh points inside sphere.
+    A \c topoSetPointSource to select points
+    which are inside a given bounding sphere.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type     | Location
-        origin      | The origin (centre) of the sphere     | yes   |
+      output    | pointSet | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        radius      | The (outer) radius of sphere          | yes   |
-        innerRadius | The inner radius of sphere            | no    | 0
-        centre      | Alternative for 'origin'              | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      sphereToPoint;
+        origin      (0 0 0);
+        radius      0.5;
+
+        // Optional entries
+        innerRadius 0;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                           | Type | Req'd | Dflt
+      name       | Name of pointSet                      | word |  yes  | -
+      type       | Type name: pointSet                   | word |  yes  | -
+      action     | Action applied on points - see below  | word |  yes  | -
+      source     | Source name: sphereToPoint            | word |  yes  | -
+      origin     | The origin (centre) of the sphere     | vector | yes | -
+      radius     | The (outer) radius of sphere          | scalar | yes | -
+      innerRadius | The inner radius of sphere           | scalar | no  | 0
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     sphereToPoint.C
 
@@ -61,8 +101,7 @@ class sphereToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -117,7 +156,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/surfaceToPoint/surfaceToPoint.H

@@ -28,25 +28,70 @@ Class
     Foam::surfaceToPoint
 
 Description
-    A topoSetPointSource to select points based on relation to surface.
+    A \c topoSetPointSource to select points based on
+    relation to a surface given by an external file.
 
-    Select based on:
+    \c surfaceToPoint can select based on:
     - distance to surface
     - inside/outside status to surface
       (Uses normal of nearest surface triangle so requires valid surface
-      topology!)
+      topology.)
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand    | Type       | Location
-        file        | The surface "filename"            | yes   |
+      input      | triSurface | $FOAM_CASE/constant/triSurface/\<file\>
-        fileType    | The surface format                | no    |
+      output     | pointSet   | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        scale       | Surface scaling factor            | no    | -1
-        nearDistance   | Near distance to the surface   | yes   |
-        includeInside  | Include inside cells (bool)    | yes   |
-        includeOutside | Include outside cells (bool)   | yes   |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name            <name>;
+        type            pointSet;
+        action          <action>;
+
+        // Mandatory entries
+        source          surfaceToPoint;
+        file            <surfaceFileName>;
+        includeInside   false;
+        includeOutside  true;
+        nearDistance    0.5;
+
+        // Optional entries
+        fileType        stl;
+        scale           2.0;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                           | Type | Req'd | Dflt
+      name       | Name of pointSet                      | word |  yes  | -
+      type       | Type name: pointSet                   | word |  yes  | -
+      action     | Action applied on points - see below  | word |  yes  | -
+      source     | Source name: surfaceToPoint           | word |  yes  | -
+      file       | The surface "filename"                | word |  yes  | -
+      fileType   | The format of the surface file        | word |  no   | ""
+      nearDistance | Near distance to the surface        | scalar | yes | -
+      includeInside | Flag to include inside cells       | bool |  yes  | -
+      includeOutside | Flag to include outside cells     | bool |  yes  | -
+      scale        | Surface scaling factor              | scalar | no  | -1
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     surfaceToPoint.C
 
@@ -102,11 +147,13 @@ class surfaceToPoint
         //- Check settings at construction time.
         void checkSettings() const;
 
+
 public:
 
     //- Runtime type information
     TypeName("surfaceToPoint");
 
+
     // Constructors
 
         //- Construct from components
@@ -137,7 +184,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointSources/topoSetPointSource/topoSetPointSource.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,7 +27,11 @@ Class
     Foam::topoSetPointSource
 
 Description
-    Base class of a topoSet source for selecting points.
+    The \c topoSetPointSource is a intermediate class
+    for handling \c topoSet sources for selecting points.
+
+    The class is not an executable \c topoSet itself,
+    yet a provider for common entries to its derived \c topoSet.
 
 SourceFiles
     topoSetPointSource.C

src/meshTools/sets/pointSources/zoneToPoint/zoneToPoint.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,18 +28,73 @@ Class
     Foam::zoneToPoint
 
 Description
-    A topoSetPointSource to select points based on one or more pointZones.
+    A \c topoSetPointSource to convert \c pointZone(s) to a \c pointSet.
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                           | Required | Default
+      Operand   | Type         | Location
-        zones       | The point zone names or regexs        | possibly |
+      input     | pointZone(s) | $FOAM_CASE/constant/polyMesh/pointZones
-        zone        | The point zone name or regex          | possibly |
+      output    | pointSet     | $FOAM_CASE/constant/polyMesh/sets/\<set\>
-        name        | Older specification for 'zone'        | no    |
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      zoneToPoint;
+
+        // Conditional mandatory entries
+        // Select either of the below
+
+        // Option-1
+        zones
+        (
+            <pointZoneName0>
+            <pointZoneName1>
+            ...
+        );
+
+        // Option-2
+        zone     <pointZoneName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                           | Type | Req'd | Dflt
+      name       | Name of pointSet                      | word |  yes  | -
+      type       | Type name: pointSet                   | word |  yes  | -
+      action     | Action applied on points - see below  | word |  yes  | -
+      source     | Source name: zoneToPoint              | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointSet from selected points
+      add      | Add selected points into this pointSet
+      subtract | Remove selected points from this pointSet
+    \endverbatim
+
+    Options for the conditional mandatory entries:
+    \verbatim
+      Entry    | Description                | Type     | Req'd  | Dflt
+      zones    | Names of input pointZones  | wordList | cond'l | -
+      zone     | Name of input pointZone    | word     | cond'l | -
+    \verbatim
+
 Note
-    Must specify "zones", "zone" or "name" (highest to lowest precedence).
+    The order of precedence among the conditional mandatory entries from the
+    highest to the lowest is \c zones, and \c zone.
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
 
 SourceFiles
     zoneToPoint.C
@@ -65,8 +120,7 @@ class zoneToPoint
 :
     public topoSetPointSource
 {
-
+    // Private Data
-    // Private data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -85,6 +139,7 @@ public:
     //- Runtime type information
     TypeName("zoneToPoint");
 
+
     // Constructors
 
         //- Construct from components
@@ -108,7 +163,6 @@ public:
             const topoSetSource::setAction action,
             topoSet& set
         ) const;
-
 };
 
 

src/meshTools/sets/pointZoneSources/setToPointZone/setToPointZone.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,53 @@ Class
     Foam::setToPointZone
 
 Description
-    A topoSetSource to select points based on usage in a pointSet.
+    A \c topoSetSource to convert a \c pointSet
+    to a \c pointZone (and associated \c pointSet).
 
-    \heading Dictionary parameters
+    Operands:
     \table
-        Property    | Description                       | Required  | Default
+      Operand   | Type      | Location
-        set         | Name of input pointSet            | yes   |
+      input     | pointSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 1  | pointSet  | $FOAM_CASE/constant/polyMesh/sets/\<set\>
+      output 2  | pointZone | $FOAM_CASE/constant/polyMesh/pointZones
     \endtable
 
+Usage
+    Minimal example by using \c system/topoSetDict.actions:
+    \verbatim
+    {
+        // Mandatory (inherited) entries
+        name        <name>;
+        type        pointZoneSet;
+        action      <action>;
+
+        // Mandatory entries
+        source      setToCellZone;
+        set         <pointSetName>;
+    }
+    \endverbatim
+
+    where the entries mean:
+    \table
+      Property   | Description                           | Type | Req'd | Dflt
+      name       | Name of pointZone                     | word |  yes  | -
+      type       | Type name: pointZoneSet               | word |  yes  | -
+      action     | Action applied on points - see below  | word |  yes  | -
+      source     | Source name: setToPointZone           | word |  yes  | -
+      set        | Name of input pointSet                | word |  yes  | -
+    \endtable
+
+    Options for the \c action entry:
+    \verbatim
+      new      | Create a new pointZone from selected points of a pointSet
+      add      | Add selected points of a pointSet into this pointZone
+      subtract | Remove selected points of a pointSet from this pointZone
+    \endverbatim
+
+See also
+    - Foam::topoSetSource
+    - Foam::topoSetPointSource
+
 SourceFiles
     setToPointZone.C
 
@@ -59,7 +98,7 @@ class setToPointZone
 :
     public topoSetSource
 {
-    // Private data
+    // Private Data
 
         //- Add usage string
         static addToUsageTable usage_;
@@ -67,11 +106,13 @@ class setToPointZone
         //- Name of set to use
         word setName_;
 
+
 public:
 
     //- Runtime type information
     TypeName("setToPointZone");
 
+
     // Constructors
 
         //- Construct from components

src/meshTools/sets/topoSetSource/topoSetSource.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2018-2019 OpenCFD Ltd.
+    Copyright (C) 2018-2020 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,10 +28,10 @@ Class
     Foam::topoSetSource
 
 Description
-    Base class of a source for a topoSet.
+    Base class of a source for a \c topoSet.
 
-    Implementer must modify the given set (see applyToSet) according to
+    Implementer must modify the given set (see \c applyToSet) according to
-    its function and the setAction (one of add/delete/new)
+    its function and the \c setAction (one of add/delete/new).
 
 SourceFiles
     topoSetSource.C

src/meshTools/sets/topoSets/cellZoneSet.H

@@ -53,7 +53,7 @@ class cellZoneSet
 :
     public cellSet
 {
-    // Private data
+    // Private Data
 
         const polyMesh& mesh_;
 

src/meshTools/sets/topoSets/faceSet.H

@@ -53,7 +53,6 @@ class faceSet
 :
     public topoSet
 {
-
 public:
 
     //- Runtime type information
@@ -145,7 +144,6 @@ public:
             const primitiveMesh&,
             const label maxLen
         ) const;
-
 };
 
 

src/meshTools/sets/topoSets/faceZoneSet.H

@@ -54,7 +54,7 @@ class faceZoneSet
 :
     public faceSet
 {
-    // Private data
+    // Private Data
 
         const polyMesh& mesh_;
 

src/meshTools/sets/topoSets/pointSet.H

@@ -144,7 +144,6 @@ public:
             const primitiveMesh&,
             const label maxLen
         ) const;
-
 };
 
 

src/meshTools/sets/topoSets/pointZoneSet.H

@@ -54,7 +54,7 @@ class pointZoneSet
 :
     public pointSet
 {
-    // Private data
+    // Private Data
 
         const polyMesh& mesh_;
 

src/meshTools/sets/topoSets/topoBitSet.H

@@ -55,7 +55,7 @@ class topoBitSet
 {
 protected:
 
-    // Protected data
+    // Protected Data
 
         bitSet selected_;
 
@@ -154,7 +154,6 @@ public:
 
         //- Subtract elements present in set.
         virtual void subtractSet(const topoSet& set);
-
 };
 
 

src/meshTools/sets/topoSets/topoBoolSet.H

@@ -55,7 +55,7 @@ class topoBoolSet
 {
 protected:
 
-    // Protected data
+    // Protected Data
 
         boolList selected_;
 
@@ -154,7 +154,6 @@ public:
 
         //- Subtract elements present in set.
         virtual void subtractSet(const topoSet& set);
-
 };
 
 

src/meshTools/sets/topoSets/topoSet.H

@@ -30,9 +30,6 @@ Class
 Description
     General set of labels of mesh quantity (points, cells, faces).
 
-    Contains various 'notImplemented' functions, but I do not want to make
-    this class abstract since it is quite handy to work on topoSets.
-
 SourceFiles
     topoSet.C
     topoSetTemplates.C

tutorials/incompressible/pisoFoam/RAS/cavity/system/topoSetDict

@@ -0,0 +1,691 @@
+/*--------------------------------*- C++ -*----------------------------------*\
+| =========                 |                                                 |
+| \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
+|  \\    /   O peration     | Version:  v1912                                 |
+|   \\  /    A nd           | Website:  www.openfoam.com                      |
+|    \\/     M anipulation  |                                                 |
+\*---------------------------------------------------------------------------*/
+FoamFile
+{
+    version     2.0;
+    format      ascii;
+    class       dictionary;
+    object      topoSetDict;
+}
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+actions
+(
+    {
+        name    boundary1;
+        type    cellSet;
+        action  new;
+        source  boundaryToCell;
+    }
+
+    {
+        name    box1a;
+        type    cellSet;
+        action  new;
+        source  boxToCell;
+        boxes
+        (
+            (0 0 0) (0.05 0.05 0.01)
+            (0.1 0.1 0) (0.02 0.02 0.01)
+        );
+    }
+
+    {
+        name    box1b;
+        type    cellSet;
+        action  new;
+        source  boxToCell;
+        box     (0 0 0) (0.05 0.05 0.01);
+    }
+
+    {
+        name    box1c;
+        type    cellSet;
+        action  new;
+        source  boxToCell;
+        min     (0 0 0);
+        max     (0.05 0.05 0.01);
+    }
+
+    {
+        name    box1c;
+        type    cellSet;
+        action  add;
+        source  boxToCell;
+        min     (0.05 0.05 0);
+        max     (0.1 0.1 0.01);
+    }
+
+    {
+        name    box1c;
+        type    cellSet;
+        action  subtract;
+        source  boxToCell;
+        min     (0 0 0);
+        max     (0.05 0.05 0.01);
+    }
+
+    {
+        name    cell1a;
+        type    cellSet;
+        action  new;
+        source  cellToCell;
+        sets
+        (
+            box1a
+            box1b
+            box1c
+        );
+    }
+
+    {
+        name    cell1b;
+        type    cellSet;
+        action  new;
+        source  cellToCell;
+        set     boundary1;
+    }
+
+    {
+        name          cylinderAnnulus1;
+        type          cellSet;
+        action        new;
+        source        cylinderAnnulusToCell;
+        p1            (0.05 0.05 0);
+        p2            (0.05 0.05 0.01);
+        outerRadius   0.06;
+        innerRadius   0.01;
+    }
+
+    {
+        name          cylinder1;
+        type          cellSet;
+        action        new;
+        source        cylinderToCell;
+        p1            (0.05 0.05 0);
+        p2            (0.05 0.05 0.01);
+        radius        0.06;
+        innerRadius   0.01;
+    }
+
+    {
+        name    field1;
+        type    cellSet;
+        action  new;
+        source  fieldToCell;
+        field   p;
+        min     0;
+        max     10;
+    }
+
+    {
+        name    cylinder1;
+        type    cellSet;
+        action  add;
+        source  haloToCell;
+        steps   2;
+    }
+
+    {
+        name    label1;
+        type    cellSet;
+        action  new;
+        source  labelToCell;
+        value
+        (
+            21
+            10
+            2
+        );
+    }
+
+    {
+        name    nbr1;
+        type    cellSet;
+        action  new;
+        source  nbrToCell;
+        neighbours 2;
+    }
+
+    {
+        name    nearest1;
+        type    cellSet;
+        action  new;
+        source  nearestToCell;
+        points
+        (
+            (0 0 0)
+            (0 0 1)
+        );
+    }
+
+    {
+        name    patch1a;
+        type    cellSet;
+        action  new;
+        source  patchToCell;
+        patches
+        (
+            movingWall
+            fixedWalls
+        );
+    }
+
+    {
+        name    patch1b;
+        type    cellSet;
+        action  new;
+        source  patchToCell;
+        patch   movingWall;
+    }
+
+    {
+        name    rotatedBox1;
+        type    cellSet;
+        action  new;
+        source  rotatedBoxToCell;
+        origin  (0 0 0);
+        i       (0.02 0.02 0);
+        j       (-0.02 0.02 0);
+        k       (0 0 100);
+    }
+
+    // {
+    //     name         searchableSurface1;
+    //     type         cellSet; // faceSet; // faceZoneSet; // pointSet;
+    //     action       new;
+    //     source       searchableSurfaceToCell; // searchableSurfaceToFace;
+    //                                           // searchableSurfaceToFaceZone;
+    //                                           // searchableSurfaceToPoint;
+    //     surfaceType  triSurfaceMesh;
+    //     surfaceName  blob.obj;
+    // }
+
+    {
+        name    shape1;
+        type    cellSet;
+        action  new;
+        source  shapeToCell;
+        shape   hex;
+    }
+
+    {
+        name        sphere1;
+        type        cellSet;
+        action      new;
+        source      sphereToCell;
+        origin      (0 0 0);
+        radius      0.05;
+        innerRadius 0.01;
+    }
+
+    // {
+    //    name            surface1;
+    //    type            cellSet; // pointSet;
+    //    action          new;
+    //    source          surfaceToCell; // surfaceToPoint;
+    //    file            "geometry.stl";
+    //    outsidePoints   ((-99 -99 -59));
+    //    includeCut      false;
+    //    includeInside   false;
+    //    includeOutside  false;
+    //    nearDistance    -1;
+    //    curvature       0.9;
+    //    useSurfaceOrientation false;
+    // }
+
+    {
+        name    targetVolume1;
+        type    cellSet;
+        action  new;
+        source  targetVolumeToCell;
+        volume  0.00001;
+        normal  (1 0 0);
+    }
+
+    {
+        name    zone1;
+        type    cellZoneSet;
+        action  new;
+        source  setToCellZone;
+        set     targetVolume1;
+    }
+
+    {
+        name    faceBoundary1;
+        type    faceSet;
+        action  new;
+        source  boundaryToFace;
+    }
+
+    {
+        name    faceBox1a;
+        type    faceSet;
+        action  new;
+        source  boxToFace;
+        boxes
+        (
+            (0 0 0) (0.05 0.05 0.01)
+            (0.1 0.1 0) (0.02 0.02 0.01)
+        );
+    }
+
+    {
+        name    faceBox1b;
+        type    faceSet;
+        action  new;
+        source  boxToFace;
+        box     (0 0 0) (0.05 0.05 0.01);
+    }
+
+    {
+        name    faceBox1c;
+        type    faceSet;
+        action  new;
+        source  boxToFace;
+        min     (0 0 0);
+        max     (0.05 0.05 0.01);
+    }
+
+    {
+        name    faceCell1a;
+        type    faceSet;
+        action  new;
+        source  cellToFace;
+        option  all;
+        sets
+        (
+            sphere1
+            box1a
+        );
+    }
+
+    {
+        name    faceCell1b;
+        type    faceSet;
+        action  new;
+        source  cellToFace;
+        option  both;
+        set     cylinder1;
+    }
+
+    {
+        name          faceCylinderAnnulus1;
+        type          faceSet;
+        action        new;
+        source        cylinderAnnulusToFace;
+        p1            (0.05 0.05 0);
+        p2            (0.05 0.05 0.01);
+        outerRadius   0.06;
+        innerRadius   0.01;
+    }
+
+    {
+        name          faceCylinder1;
+        type          faceSet;
+        action        new;
+        source        cylinderToFace;
+        p1            (0.05 0.05 0);
+        p2            (0.05 0.05 0.01);
+        radius        0.06;
+        innerRadius   0.01;
+    }
+
+    {
+        name    faceFace1a;
+        type    faceSet;
+        action  new;
+        source  faceToFace;
+        sets
+        (
+            faceCylinderAnnulus1
+            faceCylinder1
+        );
+    }
+
+    {
+        name    faceFace1b;
+        type    faceSet;
+        action  new;
+        source  faceToFace;
+        set     faceCylinder1;
+    }
+
+    {
+        name    faceLabel1;
+        type    faceSet;
+        action  new;
+        source  labelToFace;
+        value
+        (
+            21
+            10
+            2
+        );
+    }
+
+    {
+        name    faceNormal1;
+        type    faceSet;
+        action  new;
+        source  normalToFace;
+        normal  (0 0 1);
+        cos     0.01;
+    }
+
+    {
+        name    facePatch1;
+        type    faceSet;
+        action  new;
+        source  patchToFace;
+        patches
+        (
+            fixedWalls
+            movingWall
+        );
+    }
+
+    {
+        name    facePatch1;
+        type    faceSet;
+        action  subtract;
+        source  patchToFace;
+        patch   fixedWalls;
+    }
+
+    {
+        name        faceSphere1;
+        type        faceSet;
+        action      new;
+        source      sphereToFace;
+        origin      (0 0 0);
+        radius      0.05;
+        innerRadius 0.01;
+    }
+
+    {
+        name    faceZone1;
+        type    faceZoneSet;
+        action  new;
+        source  setToFaceZone;
+        faceSet faceSphere1;
+    }
+
+    {
+        name    faceZoneToFaceZone1;
+        type    faceZoneSet;
+        action  new;
+        source  faceZoneToFaceZone;
+        zone    faceZone1;
+    }
+
+    {
+        name    setAndNormalToFaceZone1;
+        type    faceZoneSet;
+        action  new;
+        source  setAndNormalToFaceZone;
+        faceSet faceSphere1;
+        normal  (1 0 0);
+    }
+
+    // {
+    //     name    faceZone1;
+    //     type    faceZoneSet;
+    //     action  new;
+    //     source  setsToFaceZone;
+    //     faceSet faceBox1a;
+    //     cellSet box1a;
+    //     flip    true;
+    // }
+
+    {
+        name    pointBox1;
+        type    pointSet;
+        action  new;
+        source  boxToPoint;
+        boxes
+        (
+            (0 0 0) (0.05 0.05 0.01)
+            (0.1 0.1 0) (0.02 0.02 0.01)
+        );
+    }
+
+    {
+        name    pointCell1;
+        type    pointSet;
+        action  new;
+        source  cellToPoint;
+        option  all;
+        sets
+        (
+            box1a
+            box1b
+            box1c
+        );
+    }
+
+    {
+        name          pointCylinder1;
+        type          pointSet;
+        action        new;
+        source        cylinderToPoint;
+        p1            (0.05 0.05 0);
+        p2            (0.05 0.05 0.01);
+        radius        0.06;
+        innerRadius   0.01;
+    }
+
+    {
+        name    pointFace1;
+        type    pointSet;
+        action  new;
+        source  faceToPoint;
+        option  all;
+        set     faceSphere1;
+    }
+
+    {
+        name    pointLabel1;
+        type    pointSet;
+        action  new;
+        source  labelToPoint;
+        value
+        (
+            21
+            10
+            2
+        );
+    }
+
+    {
+        name    pointNearest1;
+        type    pointSet;
+        action  new;
+        source  nearestToPoint;
+        points
+        (
+            (0 0 0)
+            (0 0 1)
+        );
+    }
+
+    {
+        name    pointPoint1;
+        type    pointSet;
+        action  new;
+        source  pointToPoint;
+        option  any;
+        sets
+        (
+            pointNearest1
+        );
+    }
+
+    {
+        name        pointSphere1;
+        type        pointSet;
+        action      new;
+        source      sphereToPoint;
+        origin      (0 0 0);
+        radius      0.05;
+        innerRadius 0.01;
+    }
+
+    {
+        name    pointZone1;
+        type    pointZoneSet;
+        action  new;
+        source  setToPointZone;
+        set     pointSphere1;
+    }
+
+    {
+        name    pointPoint1;
+        type    pointSet;
+        action  new;
+        source  zoneToPoint;
+        zones
+        (
+            pointZone1
+        );
+    }
+
+
+    // Mixed sets
+    {
+        name    faceCell1;
+        type    faceSet;
+        action  new;
+        source  faceToCell;
+        option  all;
+        sets
+        (
+            faceSphere1
+            faceLabel1
+        );
+    }
+
+    {
+        name    faceCell2;
+        type    faceSet;
+        action  new;
+        source  faceToCell;
+        option  owner;
+        set     faceSphere1;
+    }
+
+    {
+        name    faceZoneCell1;
+        type    cellSet;
+        action  new;
+        source  faceZoneToCell;
+        option  slave;
+        zones
+        (
+            faceZone1
+        );
+    }
+
+    {
+        name    faceZoneCell2;
+        type    cellSet;
+        action  new;
+        source  faceZoneToCell;
+        option  master;
+        zone    faceZone1;
+    }
+
+    {
+        name    pointCell2;
+        type    pointSet;
+        action  new;
+        source  pointToCell;
+        option  any;
+        sets
+        (
+            pointSphere1
+            pointNearest1
+        );
+    }
+
+    {
+        name    pointCell2;
+        type    pointSet;
+        action  new;
+        source  pointToCell;
+        option  edge;
+        set     pointNearest1;
+    }
+
+    {
+        name    region1;
+        type    cellSet;
+        action  new;
+        source  regionToCell;
+        insidePoints
+        (
+            (0.025 0.025 0.005)
+        );
+        set     box1c;
+        nErode  0;
+    }
+
+    {
+        name    zone2;
+        type    cellSet;
+        action  new;
+        source  zoneToCell;
+        zones
+        (
+            zone1
+        );
+    }
+
+    {
+        name    zone2;
+        type    cellSet;
+        action  subtract;
+        source  zoneToCell;
+        zone    zone1;
+    }
+
+    {
+        name    pointFace1;
+        type    pointSet;
+        action  new;
+        source  pointToFace;
+        option  all;
+        sets
+        (
+            pointNearest1
+        );
+    }
+
+    {
+        name      regionFace1;
+        type      faceSet;
+        action    new;
+        source    regionToFace;
+        set       faceSphere1;
+        nearPoint (1 0 0);
+    }
+
+    {
+        name    faceZone2;
+        type    faceSet;
+        action  new;
+        source  zoneToFace;
+        zones
+        (
+            faceZone1
+        );
+    }
+);
+
+
+// ************************************************************************* //