DOC: Add documentation to __add__

doc/source/reference/frame.rst

@@ -83,6 +83,7 @@ Binary operator functions
 .. autosummary::
    :toctree: api/
 
+   DataFrame.__add__
    DataFrame.add
    DataFrame.sub
    DataFrame.mul

pandas/core/arraylike.py

@@ -97,6 +97,92 @@ def _arith_method(self, other, op):
 
     @unpack_zerodim_and_defer("__add__")
     def __add__(self, other):
+        """
+        Get Addition of DataFrame and other, column-wise.
+
+        Equivalent to ``DataFrame.add(other)``.
+
+        Parameters
+        ----------
+        other : scalar, sequence, Series, dict or DataFrame
+            Object to be added to the DataFrame.
+
+        Returns
+        -------
+        DataFrame
+            The result of adding ``other`` to DataFrame.
+
+        See Also
+        --------
+        DataFrame.add : Add a DataFrame and another object, with option for index-
+            or column-oriented addition.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'height': [1.5, 2.6], 'weight': [500, 800]},
+        ...                   index=['elk', 'moose'])
+        >>> df
+                height	weight
+        elk	1.5	    500
+        moose	2.6	    800
+
+        Adding a scalar affects all rows and columns.
+
+        >>> df[['height', 'weight']] + 1.5
+                height	weight
+        elk	3.0	    501.5
+        moose	4.1	    801.5
+
+        Each element of a list is added to a column of the DataFrame, in order.
+
+        >>> df[['height', 'weight']] + [0.5, 1.5]
+                height	weight
+        elk	2.0	    501.5
+        moose	3.1	    801.5
+
+        Keys of a dictionary are aligned to the DataFrame, based on column names;
+        each value in the dictionary is added to the corresponding column.
+
+        >>> df + {'height': 0.5, 'weight': 1.5}
+                height	weight
+        elk	2.0	    501.5
+        moose	3.1	    801.5
+
+        When `other` is a :class:`Series`, the index of `other` is aligned with the
+        columns of the DataFrame.
+
+        >>> s1 = pd.Series([0.5, 1.5], index=['weight', 'height'])
+        >>> df[['height', 'weight']] + s1
+                height	weight
+        elk	3.0	    500.5
+        moose	4.1	    800.5
+
+        Even when the index of `other` is the same as the index of the DataFrame,
+        the :class:`Series` will not be reoriented. If index-wise alignment is desired,
+        :meth:`DataFrame.add` should be used with `axis='index'`.
+
+        >>> s2 = pd.Series([0.5, 1.5], index=['elk', 'moose'])
+        >>> df[['height', 'weight']] + s2
+                elk	    height	moose	weight
+        elk	NaN	    NaN	    NaN	    NaN
+        moose	NaN	    NaN	    NaN	    NaN
+
+        >>> df[['height', 'weight']].add(s2, axis='index')
+                height	weight
+        elk	2.0	    500.5
+        moose	4.1	    801.5
+
+        When `other` is a :class:`DataFrame`, both columns names and the
+        index are aligned.
+
+        >>> other = pd.DataFrame({'height': [0.2, 0.4, 0.6]},
+        ...                      index=['elk', 'moose', 'deer'])
+        >>> df + other
+                height	weight
+        deer	NaN	    NaN
+        elk	1.7	    NaN
+        moose	3.0	    NaN
+        """
         return self._arith_method(other, operator.add)
 
     @unpack_zerodim_and_defer("__radd__")