Repository: pyvista/pyvista

Issue:
Very minor irritation: filters with `inplace=True` should return self
There's a common pattern in `pyvista.core.filters` along the lines of `if inplace: return None`. My intutition is that all filters should return a mesh, whether it's a newly created one or `self` modified in place. Happy to submit a PR to change this behavior, but maybe there's a good reason for it I'm unaware of?

Discussion:
codecov[bot]: # [Codecov](https://codecov.io/gh/pyvista/pyvista/pull/1299?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pyvista) Report
> Merging [#1299](https://codecov.io/gh/pyvista/pyvista/pull/1299?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pyvista) (cbaa11c) into [master](https://codecov.io/gh/pyvista/pyvista/commit/2a227aed2eeea1cf419f60b45cb27ab1be419a95?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=pyvista) (2a227ae) will **increase** coverage by `0.00%`.
> The diff coverage is `92.10%`.

```diff
@@           Coverage Diff           @@
##           master    #1299   +/-   ##
=======================================
  Coverage   89.55%   89.56%           
=======================================
  Files          56       56           
  Lines       11406    11428   +22     
=======================================
+ Hits        10215    10235   +20     
- Misses       1191     1193    +2     
```

adeak: I understand why tests are failing on linux, but I don't understand why they aren't failing elsewhere.

The doctests that include `inplace=True` used to return `None`, so in an example
```py
>>> mesh.filter(inplace=True)
```
had no interactive output. With the current change the above call will return a mesh, so the doctest (which expects no output) will fail.

To fix this we should assign the return value to a name,
```py
>>> filtered = mesh.filter(inplace=True)
```
darikg: Ahh, thank you @adeak 
akaszynski: @adeak I think this is good to go, but you're generally more thorough.  Can you take a quick look at this PR?  I managed to fix the doctests.

Patch:
diff --git a/pyvista/core/filters.py b/pyvista/core/filters.py
index eb1fa0e8..f301edaa 100644
--- a/pyvista/core/filters.py
+++ b/pyvista/core/filters.py
@@ -115,7 +115,7 @@ class DataSetFilters:
             The default value is 0.0.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         return_clipped : bool, optional
             Return both unclipped and clipped parts of the dataset.
@@ -123,10 +123,8 @@ class DataSetFilters:
         Returns
         -------
         mesh : pyvista.PolyData or tuple(pyvista.PolyData)
-            Clipped mesh when ``inplace=False``.  When
-            ``inplace=True``, ``None``. When ``return_clipped=True``,
-            a tuple containing the unclipped and clipped datasets,
-            regardless of the setting of ``inplace``.
+            Clipped mesh when ``return_clipped=False``,
+            otherwise a tuple containing the unclipped and clipped datasets.
 
         Examples
         --------
@@ -158,13 +156,12 @@ class DataSetFilters:
                                                     invert=invert, value=value,
                                                     return_clipped=return_clipped)
         if inplace:
-            overwrite_with = result[0] if return_clipped else result
-            dataset.overwrite(overwrite_with)
             if return_clipped:
-                # normally if inplace=True, filters return None. But if
-                # return_clipped=True, the user still wants the clipped data,
-                # so return both the unclipped and clipped data as a tuple
-                return result
+                dataset.overwrite(result[0])
+                return dataset, result[1]
+            else:
+                dataset.overwrite(result)
+                return dataset
         else:
             return result
 
@@ -268,7 +265,7 @@ class DataSetFilters:
         >>> import pyvista as pv
         >>> sphere = pv.Sphere()
         >>> plane = pv.Plane()
-        >>> sphere.compute_implicit_distance(plane, inplace=True)
+        >>> _ = sphere.compute_implicit_distance(plane, inplace=True)
         >>> dist = sphere['implicit_distance']
         >>> print(type(dist))
         <class 'numpy.ndarray'>
@@ -288,7 +285,7 @@ class DataSetFilters:
         function.FunctionValue(points, dists)
         if inplace:
             dataset.point_arrays['implicit_distance'] = pyvista.convert_array(dists)
-            return
+            return dataset
         result = dataset.copy()
         result.point_arrays['implicit_distance'] = pyvista.convert_array(dists)
         return result
@@ -310,7 +307,7 @@ class DataSetFilters:
             Set the clipping value.  The default value is 0.0.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Update mesh in-place.
 
         Returns
         -------
@@ -354,6 +351,7 @@ class DataSetFilters:
 
         if inplace:
             dataset.overwrite(result)
+            return dataset
         else:
             return result
 
@@ -995,9 +993,9 @@ class DataSetFilters:
             TOP LEFT CORNER of the plane
 
         inplace : bool, optional
-            If True, the new texture coordinates will be added to the dataset
-            inplace. If False (default), a new dataset is returned with the
-            textures coordinates
+            If True, the new texture coordinates will be added to this
+            dataset. If False (default), a new dataset is returned
+            with the textures coordinates
 
         name : str, optional
             The string name to give the new texture coordinates if applying
@@ -1033,7 +1031,7 @@ class DataSetFilters:
         dataset.GetPointData().AddArray(t_coords)
         # CRITICAL:
         dataset.GetPointData().AddArray(otc) # Add old ones back at the end
-        return # No return type because it is inplace
+        return dataset
 
     def texture_map_to_sphere(dataset, center=None, prevent_seam=True,
                               inplace=False, name='Texture Coordinates'):
@@ -1071,7 +1069,7 @@ class DataSetFilters:
 
         >>> import pyvista
         >>> sphere = pyvista.Sphere()
-        >>> sphere.texture_map_to_sphere(inplace=True)
+        >>> sphere = sphere.texture_map_to_sphere()
         >>> tex = examples.download_puppy_texture()  # doctest:+SKIP
         >>> sphere.plot(texture=tex)  # doctest:+SKIP
         """
@@ -1094,7 +1092,7 @@ class DataSetFilters:
         dataset.GetPointData().AddArray(t_coords)
         # CRITICAL:
         dataset.GetPointData().AddArray(otc)  # Add old ones back at the end
-        return  # No return type because it is inplace
+        return dataset
 
     def compute_cell_sizes(dataset, length=True, area=True, volume=True,
                            progress_bar=False):
@@ -1302,7 +1300,7 @@ class DataSetFilters:
         Parameters
         ----------
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
@@ -1313,6 +1311,7 @@ class DataSetFilters:
         mesh = DataSetFilters.connectivity(dataset, largest=True)
         if inplace:
             dataset.overwrite(mesh)
+            return dataset
         else:
             return mesh
 
@@ -1390,8 +1389,9 @@ class DataSetFilters:
             if isinstance(dataset, (_vtk.vtkImageData, _vtk.vtkRectilinearGrid)):
                 raise TypeError("This filter cannot be applied inplace for this mesh type.")
             dataset.overwrite(output)
-            return
-        return output
+            return dataset
+        else:
+            return output
 
     def warp_by_vector(dataset, vectors=None, factor=1.0, inplace=False):
         """Warp the dataset's points by a point data vectors array's values.
@@ -1412,8 +1412,7 @@ class DataSetFilters:
             be used to enhance the warping effect.
 
         inplace : bool, optional
-            If True, the function will update the mesh in-place and
-            return ``None``.
+            If True, the function will update the mesh in-place.
 
         Returns
         -------
@@ -1440,8 +1439,9 @@ class DataSetFilters:
         warped_mesh = _get_output(alg)
         if inplace:
             dataset.overwrite(warped_mesh)
-            return
-        return warped_mesh
+            return dataset
+        else:
+            return warped_mesh
 
     def cell_data_to_point_data(dataset, pass_cell_data=False):
         """Transform cell data into point data.
@@ -1523,12 +1523,12 @@ class DataSetFilters:
         Parameters
         ----------
         inplace : bool, optional
-            Updates mesh in-place while returning ``None``.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.UnstructuredGrid
-            Mesh containing only triangles. ``None`` when ``inplace=True``
+            Mesh containing only triangles.
 
         """
         alg = _vtk.vtkDataSetTriangleFilter()
@@ -1538,6 +1538,7 @@ class DataSetFilters:
         mesh = _get_output(alg)
         if inplace:
             dataset.overwrite(mesh)
+            return dataset
         else:
             return mesh
 
@@ -2691,12 +2692,12 @@ class DataSetFilters:
             Defaults to True
 
         inplace : bool, optional
-            Return new mesh or overwrite input.
+            Updates existing dataset with the extracted features.
 
         Returns
         -------
         edges : pyvista.vtkPolyData
-            Extracted edges. None if inplace=True.
+            Extracted edges.
 
         """
         if not isinstance(dataset, _vtk.vtkPolyData):
@@ -2714,6 +2715,7 @@ class DataSetFilters:
         mesh = _get_output(featureEdges)
         if inplace:
             dataset.overwrite(mesh)
+            return dataset
         else:
             return mesh
 
@@ -2747,7 +2749,7 @@ class DataSetFilters:
         Returns
         -------
         merged_grid : vtk.UnstructuredGrid
-            Merged grid.  Returned when inplace is False.
+            Merged grid.
 
         Notes
         -----
@@ -2777,6 +2779,7 @@ class DataSetFilters:
         if inplace:
             if type(dataset) == type(merged):
                 dataset.deep_copy(merged)
+                return dataset
             else:
                 raise TypeError(f"Mesh type {type(dataset)} cannot be overridden by output.")
         else:
@@ -3026,7 +3029,7 @@ class DataSetFilters:
         vtk.vtkTransform are also accepted.
 
         >>> transform_matrix = np.array([[1, 0, 0, 50], [0, 1, 0, 100], [0, 0, 1, 200], [0, 0, 0, 1]])
-        >>> mesh.transform(transform_matrix, inplace=True)
+        >>> mesh = mesh.transform(transform_matrix)
         >>> mesh.plot(show_edges=True)  # doctest:+SKIP
         """
         if isinstance(trans, _vtk.vtkMatrix4x4):
@@ -3085,10 +3088,10 @@ class DataSetFilters:
                                  f'Input was `{dataset.GetClassName()}` '
                                  f'but output is `{res.GetClassName()}`.')
             dataset.overwrite(res)
+            return dataset
         else:
             return res
 
-
     def reflect(dataset, normal, point=None, inplace=False,
                 transform_all_input_vectors=False):
         """Reflect a dataset across a plane.
@@ -3103,7 +3106,7 @@ class DataSetFilters:
             specified, this is the origin.
 
         inplace : bool, optional
-            When ``True``, modifies the dataset and returns nothing.
+            When ``True``, modifies the dataset inplace.
 
         transform_all_input_vectors: bool, optional
             When ``True``, all input vectors are transformed. Otherwise, only the
@@ -3258,12 +3261,12 @@ class PolyDataFilters(DataSetFilters):
             Mesh making the cut
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            The cut mesh when inplace=False
+            The cut mesh.
 
         """
         if not isinstance(cut, pyvista.PolyData):
@@ -3284,6 +3287,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(bfilter)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3298,12 +3302,12 @@ class PolyDataFilters(DataSetFilters):
             The mesh to add.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         joinedmesh : pyvista.PolyData
-            Initial mesh and the new mesh when inplace=False.
+            The joined mesh.
 
         """
         if not isinstance(mesh, pyvista.PolyData):
@@ -3317,6 +3321,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(vtkappend)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3335,12 +3340,12 @@ class PolyDataFilters(DataSetFilters):
             The mesh to perform a union against.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         union : pyvista.PolyData
-            The union mesh when inplace=False.
+            The union mesh.
 
         """
         if not isinstance(mesh, pyvista.PolyData):
@@ -3356,6 +3361,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(bfilter)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3368,12 +3374,12 @@ class PolyDataFilters(DataSetFilters):
             The mesh to perform a union against.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         union : pyvista.PolyData
-            The union mesh when inplace=False.
+            The union mesh.
 
         """
         if not isinstance(mesh, pyvista.PolyData):
@@ -3389,6 +3395,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(bfilter)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3538,12 +3545,12 @@ class PolyDataFilters(DataSetFilters):
         Parameters
         ----------
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Mesh containing only triangles.  None when inplace=True
+            Mesh containing only triangles.
 
         """
         trifilter = _vtk.vtkTriangleFilter()
@@ -3555,6 +3562,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(trifilter)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3593,12 +3601,12 @@ class PolyDataFilters(DataSetFilters):
             Boolean flag to control smoothing of feature edges.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Smoothed mesh. None when inplace=True.
+            Smoothed mesh.
 
         Examples
         --------
@@ -3628,6 +3636,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(alg)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3669,12 +3678,12 @@ class PolyDataFilters(DataSetFilters):
             will not occur. This may limit the maximum reduction that may be achieved.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Decimated mesh. None when inplace=True.
+            Decimated mesh.
 
         """
         alg = _vtk.vtkDecimatePro()
@@ -3690,6 +3699,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(alg)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3720,12 +3730,12 @@ class PolyDataFilters(DataSetFilters):
             The field preference when searching for the scalars array by name.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Tube-filtered mesh. None when inplace=True.
+            Tube-filtered mesh.
 
         Examples
         --------
@@ -3766,6 +3776,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(tube)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -3798,12 +3809,12 @@ class PolyDataFilters(DataSetFilters):
             Can be one of the following: 'butterfly', 'loop', 'linear'
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : Polydata object
-            pyvista polydata object.  None when inplace=True
+            pyvista polydata object.
 
         Examples
         --------
@@ -3836,6 +3847,7 @@ class PolyDataFilters(DataSetFilters):
         submesh = _get_output(sfilter)
         if inplace:
             poly_data.overwrite(submesh)
+            return poly_data
         else:
             return submesh
 
@@ -3904,7 +3916,7 @@ class PolyDataFilters(DataSetFilters):
             See scalars weight parameter. Defaults to 0.1.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         progress_bar : bool, optional
             Display a progress bar to indicate progress.
@@ -3912,7 +3924,7 @@ class PolyDataFilters(DataSetFilters):
         Returns
         -------
         outmesh : pyvista.PolyData
-            Decimated mesh.  None when inplace=True.
+            Decimated mesh.
 
         Examples
         --------
@@ -3956,6 +3968,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(alg)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -4018,12 +4031,12 @@ class PolyDataFilters(DataSetFilters):
             edge is considered "sharp". Defaults to 30.0.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing. Defaults to False.
+            Updates mesh in-place. Defaults to False.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Updated mesh with cell and point normals if inplace=False
+            Updated mesh with cell and point normals.
 
         Examples
         --------
@@ -4031,7 +4044,7 @@ class PolyDataFilters(DataSetFilters):
 
         >>> import pyvista as pv
         >>> sphere = pv.Sphere()
-        >>> sphere.compute_normals(cell_normals=False, inplace=True)
+        >>> sphere = sphere.compute_normals(cell_normals=False)
         >>> normals = sphere['Normals']
         >>> normals.shape
         (842, 3)
@@ -4080,6 +4093,7 @@ class PolyDataFilters(DataSetFilters):
 
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -4118,13 +4132,12 @@ class PolyDataFilters(DataSetFilters):
             might be produced.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing. Defaults to False.
+            Updates mesh in-place. Defaults to False.
 
         Returns
         -------
         clipped_mesh : pyvista.PolyData
-            The clipped mesh resulting from this operation when
-            ``inplace==False``.  Otherwise, ``None``.
+            The clipped mesh.
 
         Examples
         --------
@@ -4166,6 +4179,7 @@ class PolyDataFilters(DataSetFilters):
 
         if inplace:
             poly_data.overwrite(result)
+            return poly_data
         else:
             return result
 
@@ -4195,7 +4209,7 @@ class PolyDataFilters(DataSetFilters):
         Returns
         -------
         mesh : pyvista.PolyData
-            Mesh with holes filled.  None when inplace=True
+            Mesh with holes filled.
 
         Examples
         --------
@@ -4203,8 +4217,9 @@ class PolyDataFilters(DataSetFilters):
 
         >>> import pyvista as pv
         >>> sphere_with_hole = pv.Sphere(end_theta=330)
-        >>> sphere_with_hole.fill_holes(1000, inplace=True)
-        >>> edges = sphere_with_hole.extract_feature_edges(feature_edges=False, manifold_edges=False)
+        >>> sphere = sphere_with_hole.fill_holes(1000)
+        >>> edges = sphere.extract_feature_edges(feature_edges=False,
+        ...                                      manifold_edges=False)
         >>> assert edges.n_cells == 0
 
         """
@@ -4218,6 +4233,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(alg)
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -4252,7 +4268,7 @@ class PolyDataFilters(DataSetFilters):
             Turn on/off conversion of degenerate strips to polys.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.  Default True.
+            Updates mesh in-place. Default False.
 
         absolute : bool, optional
             Control if ``tolerance`` is an absolute distance or a fraction.
@@ -4263,7 +4279,7 @@ class PolyDataFilters(DataSetFilters):
         Returns
         -------
         mesh : pyvista.PolyData
-            Cleaned mesh.  ``None`` when ``inplace=True``
+            Cleaned mesh.
 
         Examples
         --------
@@ -4303,6 +4319,7 @@ class PolyDataFilters(DataSetFilters):
 
         if inplace:
             poly_data.overwrite(output)
+            return poly_data
         else:
             return output
 
@@ -4359,6 +4376,7 @@ class PolyDataFilters(DataSetFilters):
 
         if inplace:
             poly_data.overwrite(output)
+            return poly_data
         else:
             return output
 
@@ -4473,7 +4491,6 @@ class PolyDataFilters(DataSetFilters):
 
         return intersection_points, intersection_cells
 
-
     def multi_ray_trace(poly_data, origins, directions, first_point=False, retry=False):
         """Perform multiple ray trace calculations.
 
@@ -4621,13 +4638,12 @@ class PolyDataFilters(DataSetFilters):
             new mesh.
 
         inplace : bool, optional
-            Updates mesh in-place while returning nothing.
+            Updates mesh in-place.
 
         Returns
         -------
         mesh : pyvista.PolyData
-            Mesh without the points flagged for removal.  Not returned
-            when inplace=False.
+            Mesh without the points flagged for removal.
 
         ridx : np.ndarray
             Indices of new points relative to the original mesh.  Not
@@ -4692,6 +4708,7 @@ class PolyDataFilters(DataSetFilters):
         # Return vtk surface and reverse indexing array
         if inplace:
             poly_data.overwrite(newmesh)
+            return poly_data
         else:
             return newmesh, ridx
 
@@ -4788,6 +4805,7 @@ class PolyDataFilters(DataSetFilters):
         mesh = _get_output(alg).triangulate()
         if inplace:
             poly_data.overwrite(mesh)
+            return poly_data
         else:
             return mesh
 
@@ -4829,7 +4847,6 @@ class PolyDataFilters(DataSetFilters):
         alg.Update()
         return _get_output(alg)
 
-
     def project_points_to_plane(poly_data, origin=None, normal=(0, 0, 1),
                                 inplace=False):
         """Project points of this mesh to a plane.
@@ -4870,9 +4887,7 @@ class PolyDataFilters(DataSetFilters):
         # Perform projection in place on the copied mesh
         f = lambda p: plane.ProjectPoint(p, p)
         np.apply_along_axis(f, 1, mesh.points)
-        if not inplace:
-            return mesh
-        return
+        return mesh
 
     def ribbon(poly_data, width=None, scalars=None, angle=0.0, factor=2.0,
                normal=None, tcoords=False, preference='points'):
@@ -4988,7 +5003,7 @@ class PolyDataFilters(DataSetFilters):
             Direction and length to extrude the mesh in.
 
         inplace : bool, optional
-            Overwrites the original mesh inplace.
+            Overwrites the original mesh in-place.
 
         progress_bar : bool, optional
             Display a progress bar to indicate progress.
@@ -5008,9 +5023,12 @@ class PolyDataFilters(DataSetFilters):
         alg.SetInputData(poly_data)
         _update_alg(alg, progress_bar, 'Extruding')
         output = pyvista.wrap(alg.GetOutput())
-        if not inplace:
+        if inplace:
+            poly_data.overwrite(output)
+            return poly_data
+        else:
             return output
-        poly_data.overwrite(output)
+
 
     def extrude_rotate(poly_data, resolution=30, inplace=False,
                        translation=0.0, dradius=0.0, angle=360.0, progress_bar=False):
@@ -5082,9 +5100,11 @@ class PolyDataFilters(DataSetFilters):
         alg.SetAngle(angle)
         _update_alg(alg, progress_bar, 'Extruding')
         output = pyvista.wrap(alg.GetOutput())
-        if not inplace:
+        if inplace:
+            poly_data.overwrite(output)
+            return poly_data
+        else:
             return output
-        poly_data.overwrite(output)
 
     def strip(poly_data, join=False, max_length=1000, pass_cell_data=False,
               pass_cell_ids=False, pass_point_ids=False):
@@ -5150,6 +5170,7 @@ class PolyDataFilters(DataSetFilters):
         alg.Update()
         return _get_output(alg)
 
+
 @abstract_class
 class UnstructuredGridFilters(DataSetFilters):
     """An internal class to manage filters/algorithms for unstructured grid datasets."""
diff --git a/pyvista/core/pointset.py b/pyvista/core/pointset.py
index 9c460518..1ab1a5e0 100644
--- a/pyvista/core/pointset.py
+++ b/pyvista/core/pointset.py
@@ -77,7 +77,7 @@ class PointSet(DataSet):
 
         >>> import pyvista
         >>> letter_a = pyvista.examples.download_letter_a()
-        >>> letter_a.remove_cells(range(1000))
+        >>> trimmed = letter_a.remove_cells(range(1000))
         """
         if isinstance(ind, np.ndarray):
             if ind.dtype == np.bool_ and ind.size != self.n_cells:
@@ -94,8 +94,7 @@ class PointSet(DataSet):
         target.cell_arrays[_vtk.vtkDataSetAttributes.GhostArrayName()] = ghost_cells
         target.RemoveGhostCells()
 
-        if not inplace:
-            return target
+        return target
 
 
 class PolyData(_vtk.vtkPolyData, PointSet, PolyDataFilters):
@@ -1370,6 +1369,7 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
             array[ind] = _vtk.vtkDataSetAttributes.HIDDENCELL
             name = _vtk.vtkDataSetAttributes.GhostArrayName()
             self.cell_arrays[name] = array
+            return self
         else:
             grid = self.copy()
             grid.hide_cells(ind)
@@ -1389,9 +1389,10 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
 
         Returns
         -------
-        grid : ExplicitStructuredGrid or None
-            A deep copy of this grid if ``inplace=False`` or ``None``
-            otherwise.
+        grid : ExplicitStructuredGrid
+            A deep copy of this grid if ``inplace=False`` with the
+            hidden cells shown.  Otherwise, this dataset with the
+            shown cells.
 
         Examples
         --------
@@ -1410,6 +1411,7 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
                 array = self.cell_arrays[name]
                 ind = np.argwhere(array == _vtk.vtkDataSetAttributes.HIDDENCELL)
                 array[ind] = 0
+            return self
         else:
             grid = self.copy()
             grid.show_cells()
@@ -1718,9 +1720,8 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
 
         Returns
         -------
-        grid : ExplicitStructuredGrid or None
-            A deep copy of this grid if ``inplace=False`` or ``None``
-            otherwise.
+        grid : ExplicitStructuredGrid
+            A deep copy of this grid if ``inplace=False``.
 
         See Also
         --------
@@ -1738,6 +1739,7 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
         """
         if inplace:
             self.ComputeFacesConnectivityFlagsArray()
+            return self
         else:
             grid = self.copy()
             grid.compute_connectivity()
@@ -1785,6 +1787,7 @@ class ExplicitStructuredGrid(_vtk.vtkExplicitStructuredGrid, PointGrid):
             array = np.unpackbits(array, axis=1)
             array = array.sum(axis=1)
             self.cell_arrays['number_of_connections'] = array
+            return self
         else:
             grid = self.copy()
             grid.compute_connections()
diff --git a/pyvista/utilities/geometric_objects.py b/pyvista/utilities/geometric_objects.py
index 1765c724..5b140a8a 100644
--- a/pyvista/utilities/geometric_objects.py
+++ b/pyvista/utilities/geometric_objects.py
@@ -447,25 +447,25 @@ def Cone(center=(0.,0.,0.), direction=(1.,0.,0.), height=1.0, radius=None,
     Parameters
     ----------
     center : np.ndarray or list
-        Center in [x, y, z]. middle of the axis of the cone.
+        Center in [x, y, z]. Middle of the axis of the cone.
 
     direction : np.ndarray or list
-        Direction vector in [x, y, z]. orientation vector of the cone.
+        Direction vector in [x, y, z]. Orientation vector of the cone.
 
     height : float
         Height along the cone in its specified direction.
 
     radius : float
-        Base radius of the cone
+        Base radius of the cone.
 
     capping : bool
         Turn on/off whether to cap the base of the cone with a polygon.
 
     angle : float
-        The angle degrees between the axis of the cone and a generatrix.
+        The angle in degrees between the axis of the cone and a generatrix.
 
     resolution : int
-        Number of facets used to represent the cone
+        Number of facets used to represent the cone.
 
     """
     src = _vtk.vtkConeSource()
@@ -488,25 +488,21 @@ def Cone(center=(0.,0.,0.), direction=(1.,0.,0.), height=1.0, radius=None,
 
 
 def Polygon(center=(0.,0.,0.), radius=1, normal=(0,0,1), n_sides=6):
-    """Create a polygonal disk with a hole in the center.
-
-    The disk has zero height. The user can specify the inner and outer radius
-    of the disk, and the radial and circumferential resolution of the polygonal
-    representation.
+    """Create a polygon.
 
     Parameters
     ----------
     center : np.ndarray or list
-        Center in [x, y, z]. middle of the axis of the polygon.
+        Center in [x, y, z]. Middle of the axis of the polygon.
 
     radius : float
-        The radius of the polygon
+        The radius of the polygon.
 
     normal : np.ndarray or list
-        Direction vector in [x, y, z]. orientation vector of the cone.
+        Direction vector in [x, y, z]. Orientation vector of the polygon.
 
     n_sides : int
-        Number of sides of the polygon
+        Number of sides of the polygon.
 
     """
     src = _vtk.vtkRegularPolygonSource()
@@ -529,21 +525,21 @@ def Disc(center=(0., 0., 0.), inner=0.25, outer=0.5, normal=(0, 0, 1), r_res=1,
     Parameters
     ----------
     center : np.ndarray or list
-        Center in [x, y, z]. middle of the axis of the disc.
+        Center in [x, y, z]. Middle of the axis of the disc.
 
     inner : float
-        The inner radius
+        The inner radius.
 
     outer : float
-        The outer radius
+        The outer radius.
 
     normal : np.ndarray or list
-        Direction vector in [x, y, z]. orientation vector of the cone.
+        Direction vector in [x, y, z]. Orientation vector of the disc.
 
     r_res: int
         Number of points in radius direction.
 
-    r_res: int
+    c_res: int
         Number of points in circumferential direction.
 
     """


Test patch:
diff --git a/tests/test_grid.py b/tests/test_grid.py
index 06392991..c29d7ee4 100644
--- a/tests/test_grid.py
+++ b/tests/test_grid.py
@@ -960,8 +960,8 @@ def test_ExplicitStructuredGrid_hide_cells():
     assert 'vtkGhostType' not in grid.cell_arrays
     assert np.array_equal(copy.cell_arrays['vtkGhostType'], ghost)
 
-    copy = grid.hide_cells(range(80, 120), inplace=True)
-    assert copy is None
+    out = grid.hide_cells(range(80, 120), inplace=True)
+    assert out is grid
     assert 'vtkGhostType' in grid.cell_arrays
     assert np.array_equal(grid.cell_arrays['vtkGhostType'], ghost)
 
@@ -977,8 +977,8 @@ def test_ExplicitStructuredGrid_show_cells():
     assert np.count_nonzero(copy.cell_arrays['vtkGhostType']) == 0
     assert np.count_nonzero(grid.cell_arrays['vtkGhostType']) == 40
 
-    copy = grid.show_cells(inplace=True)
-    assert copy is None
+    out = grid.show_cells(inplace=True)
+    assert out is grid
     assert np.count_nonzero(grid.cell_arrays['vtkGhostType']) == 0
 
 
@@ -1069,8 +1069,8 @@ def test_ExplicitStructuredGrid_compute_connectivity():
     assert 'ConnectivityFlags' not in grid.cell_arrays
     assert np.array_equal(copy.cell_arrays['ConnectivityFlags'], connectivity)
 
-    copy = grid.compute_connectivity(inplace=True)
-    assert copy is None
+    out = grid.compute_connectivity(inplace=True)
+    assert out is grid
     assert 'ConnectivityFlags' in grid.cell_arrays
     assert np.array_equal(grid.cell_arrays['ConnectivityFlags'], connectivity)
 
@@ -1094,8 +1094,8 @@ def test_ExplicitStructuredGrid_compute_connections():
     assert np.array_equal(copy.cell_arrays['number_of_connections'],
                           connections)
 
-    copy = grid.compute_connections(inplace=True)
-    assert copy is None
+    out = grid.compute_connections(inplace=True)
+    assert out is grid
     assert 'number_of_connections' in grid.cell_arrays
     assert np.array_equal(grid.cell_arrays['number_of_connections'],
                           connections)