Repository: pandas-dev/pandas
Pull request: DOC: Corrects 'reindex_axis' docstring
The docstring included a 'tolerance' parameter which is missing from the source. This has been removed.

The docstring did not describe the 'fill_value' parameter. This has been added, mostly reusing the wording in the summary part of the existing docstring.

- [x] closes #23960
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Problem statement:
Wrong argument documentation for reindex_axis
#### Problem description

The documentation for ``DataFrame.reindex_axis()`` has incorrect documentation for the arguments. The function signature is correct, but the description of ``fill_value`` is missing and  there's a description of a ``tolerance`` argument that isn't accepted by the actual method. This can cause crashes or bad data due to incorrect use of the method.

#### Expected Output

Documentation for the ``tolerance`` argument should be removed, and a description of the ``fill_value`` argument should be added.

#### Output of ``pd.show_versions()``

<details>

INSTALLED VERSIONS
------------------
commit: None
python: 3.7.0.final.0
python-bits: 64
OS: Darwin
OS-release: 17.7.0
machine: x86_64
processor: i386
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: en_US.UTF-8

pandas: 0.23.4
pytest: None
pip: 18.1
setuptools: 40.6.2
Cython: 0.29.1
numpy: 1.15.4
scipy: None
pyarrow: 0.11.1
xarray: None
IPython: None
sphinx: None
patsy: None
dateutil: 2.7.5
pytz: 2018.7
blosc: None
bottleneck: None
tables: 3.4.4
numexpr: 2.6.8
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: None
sqlalchemy: 1.2.14
pymysql: None
psycopg2: 2.7.6.1 (dt dec pq3 ext lo64)
jinja2: None
s3fs: 0.2.0
fastparquet: 0.2.0
pandas_gbq: None
pandas_datareader: None

</details>

Hints from issue discussion:
Hi, I can take care of this if no one else is working on it.
Hm, just a clarification. I don't see a `fill_na` argument, but there is `fill_value` which doesn't have a description. Is that the argument you meant?

I'm looking [here](https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/core/frame.py#L3568-L3574).
Agh yeah that's what I meant. Nice catch! I've updated the original report.
Please take a look. I am not very savvy with github so pls let me know if I should do anything differently.

Commit message: Fixed non-functioning example.
Added periods, reformatted summary, and other changes required by
validate_docstrings.py.

Patch to review:
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 08c07da39128f..59b90bbde8550 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -4311,46 +4311,46 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
             Broadcast across a level, matching Index values on the
-            passed MultiIndex level
+            passed MultiIndex level.
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
         limit : int, default None
-            Maximum number of consecutive elements to forward or backward fill
-        tolerance : optional
-            Maximum distance between original and new labels for inexact
-            matches. The values of the index at the matching locations most
-            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
-
-            Tolerance may be a scalar value, which applies the same tolerance
-            to all values, or list-like, which applies variable tolerance per
-            element. List-like includes list, tuple, array, Series, and must be
-            the same size as the index and its dtype must exactly match the
-            index's type.
+            Maximum number of consecutive elements to forward or backward fill.
+        fill_value : float, default NaN
+            Value used to fill in locations having no value in the previous 
+            index.
 
             .. versionadded:: 0.21.0 (list-like tolerance)
 
+        Returns
+        -------
+        %(klass)s
+
         See Also
         --------
         DataFrame.set_index : Set row labels.
@@ -4358,13 +4358,16 @@ def _reindex_multi(self, axes, copy, fill_value):
         DataFrame.reindex : Change to new indices or expand indices.
         DataFrame.reindex_like : Change to same indices as other DataFrame.
 
-        Returns
-        -------
-        %(klass)s
-
         Examples
         --------
-        >>> df.reindex_axis(['A', 'B', 'C'], axis=1)
+        >>> df = pd.DataFrame(np.array(([1,2,3], [4,5,6], [7,8,9])),
+        ...                             index=['One', 'Two', 'Three'],
+        ...                             columns=['A', 'B', 'C'])
+        >>> df.reindex_axis(['B', 'C', 'D'], axis=1)
+               B  C   D
+        One    2  3 NaN
+        Two    5  6 NaN
+        Three  8  9 NaN
         """)
 
     @Appender(_shared_docs['reindex_axis'] % _shared_doc_kwargs)


Code review comments:
diff_hunk: @@ -4311,60 +4311,63 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
path: pandas/core/generic.py
text: @user1:
```suggestion
        level : int or str
```

diff_hunk: @@ -4311,60 +4311,63 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
             Broadcast across a level, matching Index values on the
-            passed MultiIndex level
+            passed MultiIndex level.
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
         limit : int, default None
-            Maximum number of consecutive elements to forward or backward fill
-        tolerance : optional
-            Maximum distance between original and new labels for inexact
-            matches. The values of the index at the matching locations most
-            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
-
-            Tolerance may be a scalar value, which applies the same tolerance
-            to all values, or list-like, which applies variable tolerance per
-            element. List-like includes list, tuple, array, Series, and must be
-            the same size as the index and its dtype must exactly match the
-            index's type.
+            Maximum number of consecutive elements to forward or backward fill.
+        fill_value : float, default NaN
+            Value used to fill in locations having no value in the previous 
+            index.
 
             .. versionadded:: 0.21.0 (list-like tolerance)
 
+        Returns
+        -------
+        %(klass)s
+
         See Also
         --------
         DataFrame.set_index : Set row labels.
         DataFrame.reset_index : Remove row labels or move them to new columns.
         DataFrame.reindex : Change to new indices or expand indices.
         DataFrame.reindex_like : Change to same indices as other DataFrame.
 
-        Returns
-        -------
-        %(klass)s
-
         Examples
         --------
-        >>> df.reindex_axis(['A', 'B', 'C'], axis=1)
+        >>> df = pd.DataFrame(np.array(([1,2,3], [4,5,6], [7,8,9])),
+        ...                             index=['One', 'Two', 'Three'],
+        ...                             columns=['A', 'B', 'C'])
path: pandas/core/generic.py
text: @user1:
It would be nice to show the original `df` first, so it's easier to compare how the original differs from the changed.

@author:
Done.

diff_hunk: @@ -4311,60 +4311,63 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
             Broadcast across a level, matching Index values on the
-            passed MultiIndex level
+            passed MultiIndex level.
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
         limit : int, default None
path: pandas/core/generic.py
text: @user1:
```suggestion
        limit : int, optional
```

diff_hunk: @@ -4311,60 +4311,63 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
             Broadcast across a level, matching Index values on the
-            passed MultiIndex level
+            passed MultiIndex level.
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
         limit : int, default None
-            Maximum number of consecutive elements to forward or backward fill
-        tolerance : optional
-            Maximum distance between original and new labels for inexact
-            matches. The values of the index at the matching locations most
-            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
-
-            Tolerance may be a scalar value, which applies the same tolerance
-            to all values, or list-like, which applies variable tolerance per
-            element. List-like includes list, tuple, array, Series, and must be
-            the same size as the index and its dtype must exactly match the
-            index's type.
+            Maximum number of consecutive elements to forward or backward fill.
+        fill_value : float, default NaN
+            Value used to fill in locations having no value in the previous 
+            index.
 
             .. versionadded:: 0.21.0 (list-like tolerance)
 
+        Returns
+        -------
+        %(klass)s
+
         See Also
         --------
         DataFrame.set_index : Set row labels.
         DataFrame.reset_index : Remove row labels or move them to new columns.
         DataFrame.reindex : Change to new indices or expand indices.
         DataFrame.reindex_like : Change to same indices as other DataFrame.
 
-        Returns
-        -------
-        %(klass)s
-
         Examples
         --------
-        >>> df.reindex_axis(['A', 'B', 'C'], axis=1)
+        >>> df = pd.DataFrame(np.array(([1,2,3], [4,5,6], [7,8,9])),
+        ...                             index=['One', 'Two', 'Three'],
+        ...                             columns=['A', 'B', 'C'])
+        >>> df.reindex_axis(['B', 'C', 'D'], axis=1)
+               B  C   D
+        One    2  3 NaN
+        Two    5  6 NaN
+        Three  8  9 NaN
path: pandas/core/generic.py
text: @user1:
For the example, do you mind using a more real-world example.

We've been using an example with animal number of legs. As everybody knows how many legs a cat or a penguin have, it makes it very easy to see what is going on in the example. You can for example see: https://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.itertuples.html

@author:
Done.

diff_hunk: @@ -4311,60 +4311,63 @@ def _needs_reindex_multi(self, axes, method, level):
     def _reindex_multi(self, axes, copy, fill_value):
         return NotImplemented
 
-    _shared_docs['reindex_axis'] = ("""Conform input object to new index
-        with optional filling logic, placing NA/NaN in locations having
-        no value in the previous index. A new object is produced unless
-        the new index is equivalent to the current one and copy=False.
+    _shared_docs['reindex_axis'] = ("""
+        Conform input object to new index.
+
+        By default, places NA/NaN in locations having no value in the
+        previous index. A new object is produced unless the new index
+        is equivalent to the current one and copy=False.
 
         Parameters
         ----------
         labels : array-like
             New labels / index to conform to. Preferably an Index object to
-            avoid duplicating data
+            avoid duplicating data.
         axis : %(axes_single_arg)s
+            Indicate whether to use rows or columns.
         method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}, optional
             Method to use for filling holes in reindexed DataFrame:
 
-            * default: don't fill gaps
+            * default: don't fill gaps.
             * pad / ffill: propagate last valid observation forward to next
-              valid
-            * backfill / bfill: use next valid observation to fill gap
-            * nearest: use nearest valid observations to fill gap
+              valid.
+            * backfill / bfill: use next valid observation to fill gap.
+            * nearest: use nearest valid observations to fill gap.
 
-        copy : boolean, default True
-            Return a new object, even if the passed indexes are the same
         level : int or name
             Broadcast across a level, matching Index values on the
-            passed MultiIndex level
+            passed MultiIndex level.
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
         limit : int, default None
-            Maximum number of consecutive elements to forward or backward fill
-        tolerance : optional
-            Maximum distance between original and new labels for inexact
-            matches. The values of the index at the matching locations most
-            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
-
-            Tolerance may be a scalar value, which applies the same tolerance
-            to all values, or list-like, which applies variable tolerance per
-            element. List-like includes list, tuple, array, Series, and must be
-            the same size as the index and its dtype must exactly match the
-            index's type.
+            Maximum number of consecutive elements to forward or backward fill.
+        fill_value : float, default NaN
+            Value used to fill in locations having no value in the previous 
+            index.
 
             .. versionadded:: 0.21.0 (list-like tolerance)
 
+        Returns
+        -------
+        %(klass)s
+
         See Also
         --------
         DataFrame.set_index : Set row labels.
         DataFrame.reset_index : Remove row labels or move them to new columns.
         DataFrame.reindex : Change to new indices or expand indices.
         DataFrame.reindex_like : Change to same indices as other DataFrame.
 
-        Returns
-        -------
-        %(klass)s
-
         Examples
         --------
-        >>> df.reindex_axis(['A', 'B', 'C'], axis=1)
+        >>> df = pd.DataFrame(np.array(([1,2,3], [4,5,6], [7,8,9])),
+        ...                             index=['One', 'Two', 'Three'],
+        ...                             columns=['A', 'B', 'C'])
+        >>> df.reindex_axis(['B', 'C', 'D'], axis=1)
path: pandas/core/generic.py
text: @user1:
I think `axis='columns'` is more explicit than `axis=``

@author:
Done.