DOC: clarify that set_coordinates modifies array of geometries in pla…

…ce (#335)

pygeos/coordinates.py

@@ -136,18 +136,29 @@ def get_coordinates(geometry, include_z=False, return_index=False):
 
 
 def set_coordinates(geometry, coordinates):
-    """Returns a copy of a geometry array with different coordinates.
+    """Adapts the coordinates of a geometry array in-place.
 
     If the coordinates array has shape (N, 2), all returned geometries
     will be two-dimensional, and the third dimension will be discarded,
     if present. If the coordinates array has shape (N, 3), the returned
     geometries preserve the dimensionality of the input geometries.
 
+    .. warning::
+
+        The geometry array is modified in-place! If you do not want to
+        modify the original array, you can do
+        ``set_coordinates(arr.copy(), newcoords)``.
+
     Parameters
     ----------
     geometry : Geometry or array_like
     coordinates: array_like
 
+    See Also
+    --------
+    apply : Returns a copy of a geometry array with a function applied to its
+        coordinates.
+
     Examples
     --------
     >>> set_coordinates(Geometry("POINT (0 0)"), [[1, 1]])