adjust for more comments

ci/doctests.sh

@@ -21,7 +21,7 @@ if [ "$DOCTEST" ]; then
 
     # DataFrame / Series docstrings
     pytest --doctest-modules -v pandas/core/frame.py \
-        -k"-assign -axes -combine -isin -itertuples -join -nlargest -nsmallest -nunique -pivot_table -quantile -query -reindex -reindex_axis -replace -round -set_index -stack -to_dict -to_stata -transform"
+        -k"-assign -axes -combine -isin -itertuples -join -nlargest -nsmallest -nunique -pivot_table -quantile -query -reindex -reindex_axis -replace -round -set_index -stack -to_dict -to_stata"
 
     if [ $? -ne "0" ]; then
         RET=1
@@ -35,7 +35,7 @@ if [ "$DOCTEST" ]; then
     fi
 
     pytest --doctest-modules -v pandas/core/generic.py \
-        -k"-_set_axis_name -_xs -describe -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values -xs"
+        -k"-_set_axis_name -_xs -describe -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transpose -values -xs"
 
     if [ $? -ne "0" ]; then
         RET=1

pandas/core/frame.py

@@ -109,10 +109,9 @@
 _shared_doc_kwargs = dict(
     axes='index, columns', klass='DataFrame',
     axes_single_arg="{0 or 'index', 1 or 'columns'}",
-    axis="""
-    axis : {0 or 'index', 1 or 'columns'}, default 0
-        - 0 or 'index': apply function to each column.
-        - 1 or 'columns': apply function to each row.""",
+    axis="""axis : {0 or 'index', 1 or 'columns'}, default 0
+        If 0 or 'index': apply function to each column.
+        If 1 or 'columns': apply function to each row.""",
     optional_by="""
         by : str or list of str
             Name or list of names to sort by.

pandas/core/generic.py

@@ -4545,16 +4545,16 @@ def pipe(self, func, *args, **kwargs):
 
     Parameters
     ----------
-    func : function, string, list of functions and/or strings or dict
+    func : function, str, list or dict
         Function to use for aggregating the data. If a function, must either
         work when passed a %(klass)s or when passed to %(klass)s.apply.
 
         Accepted combinations are:
 
-        - string function name
         - function
-        - list of functions and/or function names
-        - dict of axis labels -> functions, function names or list of such
+        - string function name
+        - list of functions and/or function names, e.g. ``[np.sum, 'mean']``
+        - dict of axis labels -> functions, function names or list of such.
     %(axis)s
     *args
         Positional arguments to pass to `func`.
@@ -4563,7 +4563,11 @@ def pipe(self, func, *args, **kwargs):
 
     Returns
     -------
-    pandas.%(klass)s
+    DataFrame, Series or scalar
+        if DataFrame.agg is called with a single function, returns a Series
+        if DataFrame.agg is called with several functions, returns a DataFrame
+        if Series.agg is called with single function, returns a scalar
+        if Series.agg is called with several functions, returns a Series
 
     Notes
     -----
@@ -4580,15 +4584,15 @@ def pipe(self, func, *args, **kwargs):
 
     Parameters
     ----------
-    func : function, string, list of functions and/or strings or dict
+    func : function, str, list or dict
         Function to use for transforming the data. If a function, must either
         work when passed a %(klass)s or when passed to %(klass)s.apply.
 
         Accepted combinations are:
 
-        - string function name
         - function
-        - list of functions and/or function names
+        - string function name
+        - list of functions and/or function names, e.g. ``[np.exp. 'sqrt']``
         - dict of axis labels -> functions, function names or list of such.
     %(axis)s
     *args
@@ -4598,31 +4602,41 @@ def pipe(self, func, *args, **kwargs):
 
     Returns
     -------
-    pandas.%(klass)s
+    %(klass)s
         A %(klass)s that must have the same length as self.
 
     Raises
     ------
-    ValueError : if the returned %(klass)s has a different length than self.
+    ValueError : If the returned %(klass)s has a different length than self.
 
     See Also
     --------
-    pandas.%(klass)s.agg : only perform aggregating type operations
-    pandas.%(klass)s.apply : Invoke function on a Series
+    %(klass)s.agg : Only perform aggregating type operations.
+    %(klass)s.apply : Invoke function on a Series.
 
     Examples
     --------
     >>> df = pd.DataFrame({'A': range(3), 'B': range(1, 4)})
+    >>> df
+       A  B
+    0  0  1
+    1  1  2
+    2  2  3
     >>> df.transform(lambda x: x + 1)
        A  B
     0  1  2
     1  2  3
     2  3  4
 
-    Even though the resulting %(klass)s must have the length as the input
-    %(klass)s, it is possible to provide several input functions:
+    Even though the resulting %(klass)s must have the same length as the
+    input %(klass)s, it is possible to provide several input functions:
 
     >>> s = pd.Series(range(3))
+    >>> s
+    0    0
+    1    1
+    2    2
+    dtype: int64
     >>> s.transform([np.sqrt, np.exp])
            sqrt        exp
     0  0.000000   1.000000

pandas/core/series.py

@@ -89,10 +89,8 @@
 
 _shared_doc_kwargs = dict(
     axes='index', klass='Series', axes_single_arg="{0 or 'index'}",
-    axis="""
-    axis : {0 or 'index'}
-        Parameter needed for compatibility with DataFrame.
-    """,
+    axis="""axis : {0 or 'index'}
+        Parameter needed for compatibility with DataFrame.""",
     inplace="""inplace : boolean, default False
         If True, performs operation inplace and returns None.""",
     unique='np.ndarray', duplicated='Series',