DOC: Improve the docstring of pandas.DataFrame.append()

pandas/core/frame.py

@@ -143,14 +143,16 @@
 ----------%s
 right : DataFrame
 how : {'left', 'right', 'outer', 'inner'}, default 'inner'
+    How to handle the operation of the two objects.
+
     * left: use only keys from left frame, similar to a SQL left outer join;
-      preserve key order
+      preserve key order.
     * right: use only keys from right frame, similar to a SQL right outer join;
-      preserve key order
+      preserve key order.
     * outer: use union of keys from both frames, similar to a SQL full outer
-      join; sort keys lexicographically
+      join; sort keys lexicographically.
     * inner: use intersection of keys from both frames, similar to a SQL inner
-      join; preserve the order of the left keys
+      join; preserve the order of the left keys.
 on : label or list
     Column or index level names to join on. These must be found in both
     DataFrames. If `on` is None and not merging on indexes then this defaults
@@ -166,18 +168,18 @@
 left_index : boolean, default False
     Use the index from the left DataFrame as the join key(s). If it is a
     MultiIndex, the number of keys in the other DataFrame (either the index
-    or a number of columns) must match the number of levels
+    or a number of columns) must match the number of levels.
 right_index : boolean, default False
     Use the index from the right DataFrame as the join key. Same caveats as
-    left_index
+    left_index.
 sort : boolean, default False
     Sort the join keys lexicographically in the result DataFrame. If False,
-    the order of the join keys depends on the join type (how keyword)
+    the order of the join keys depends on the join type (how keyword).
 suffixes : 2-length sequence (tuple, list, ...)
     Suffix to apply to overlapping column names in the left and right
-    side, respectively
+    side, respectively.
 copy : boolean, default True
-    If False, do not copy data unnecessarily
+    If False, do not copy data unnecessarily.
 indicator : boolean or string, default False
     If True, adds a column to output DataFrame called "_merge" with
     information on the source of each row.
@@ -199,7 +201,7 @@
       dataset.
     * "many_to_many" or "m:m": allowed, but does not result in checks.
 
-    .. versionadded:: 0.21.0
+    .. versionadded:: 0.21.0.
 
 Notes
 -----
@@ -2689,7 +2691,7 @@ def insert(self, loc, column, value, allow_duplicates=False):
                           allow_duplicates=allow_duplicates)
 
     def assign(self, **kwargs):
-        r"""
+        """
         Assign new columns to a DataFrame, returning a new object
         (a copy) with all the original columns in addition to the new ones.
 
@@ -5053,8 +5055,9 @@ def infer(x):
 
     def append(self, other, ignore_index=False, verify_integrity=False):
         """
-        Append rows of `other` to the end of this frame, returning a new
-        object. Columns not in this frame are added as new columns.
+        Append rows of `other` to the end of `caller`, returning a new object.
+
+        Columns not in other are added as new columns.
 
         Parameters
         ----------
@@ -5136,7 +5139,6 @@ def append(self, other, ignore_index=False, verify_integrity=False):
         2  2
         3  3
         4  4
-
         """
         if isinstance(other, (Series, dict)):
             if isinstance(other, dict):
@@ -5402,7 +5404,6 @@ def round(self, decimals=0, *args, **kwargs):
         --------
         numpy.around
         Series.round
-
         """
         from pandas.core.reshape.concat import concat