Update shell docstring, use fluent api + string selector (#1079)

* Update docstring,  use fluent api + string selector

Update the docstring for `shell` to use the string selector and fluent
api to show how to create a three faced cube.

Remove the note about shelling being a common use case for
`Workplane.add`

* Fix literal block, remove future note, minor docstring formatting

Co-authored-by: Lorenz Neureuter <[email protected]>

Author: qwelyt

cadquery/cq.py

@@ -452,7 +452,7 @@ def add(self, obj):
         then it is added.
 
         Used in rare cases when you need to combine the results of several CQ
-        results into a single Workplane object. Shelling is one common example.
+        results into a single Workplane object.
         """
         if isinstance(obj, list):
             self.objects.extend(obj)
@@ -1221,36 +1221,26 @@ def shell(
 
         To shell, first create a solid, and *in the same chain* select the faces you wish to remove.
 
-        :param thickness: a positive float, representing the thickness of the desired shell.
+        :param thickness: thickness of the desired shell.
             Negative values shell inwards, positive values shell outwards.
-        :param kind: kind of joints, intersection or arc (default: arc).
+        :param kind: kind of join, arc or intersection (default: arc).
         :raises ValueError: if the current stack contains objects that are not faces of a solid
              further up in the chain.
         :returns: a CQ object with the resulting shelled solid selected.
 
         This example will create a hollowed out unit cube, where the top most face is open,
         and all other walls are 0.2 units thick::
 
-            Workplane().box(1,1,1).faces("+Z").shell(0.2)
+            Workplane().box(1, 1, 1).faces("+Z").shell(0.2)
 
-        Shelling is one of the cases where you may need to use the add method to select several
-        faces. For example, this example creates a 3-walled corner, by removing three faces
-        of a cube::
+        You can also select multiple faces at once. Here is an example that creates a three-walled
+        corner, by removing three faces of a cube::
 
-            s = Workplane().box(1,1,1)
-            s1 = s.faces("+Z")
-            s1.add(s.faces("+Y")).add(s.faces("+X"))
-            self.saveModel(s1.shell(0.2))
-
-        This fairly yucky syntax for selecting multiple faces is planned for improvement
+            Workplane().box(10, 10, 10).faces(">Z or >X or <Y").shell(1)
 
         **Note**:  When sharp edges are shelled inwards, they remain sharp corners, but **outward**
-        shells are automatically filleted, because an outward offset from a corner generates
-        a radius.
-
-
-        Future Enhancements:
-            Better selectors to make it easier to select multiple faces
+        shells are automatically filleted (unless kind="intersection"), because an outward offset
+        from a corner generates a radius.
         """
         solidRef = self.findSolid()