DOC: elaborate the usage of topoSet

TUT: add topoSet examples to pisoFoam/RAS/cavity tutorial
  BUG: fixes #1673

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
-        value       | The cell labels                   | yes   |
+      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      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;
-
 };