DOC: inconsistent docs-string signatures for shared functions

[jreback]

xref #15580

related to this is our inconsistent treatment of the actual args in shared doc strings, e.g.

so the following have exactly the same arguments to the doc-string (except for the first 1-2 which are the axes: index, or index & columns).

The doc-strings themselves are correct, but the signature are hidden. I think easiest is simply to actually list out the args where they are defined (e.g in core/series.py for example).

Signature: pd.Series.reindex(self, index=None, **kwargs)
Docstring:
Conform Series 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

Signature: pd.SparseSeries.reindex(self, index=None, method=None, copy=True, limit=None, **kwargs)
Docstring:
Conform SparseSeries 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

Signature: pd.DataFrame.reindex(self, index=None, columns=None, **kwargs)
Docstring:
Conform DataFrame 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

There are a bunch of functions like this.

[MarianaBazely]

I searched for **kwargs on series.py, frame.py and panel.py. These are the functions that are in all the 3 (or 2) and in which signatures are not expanded:

• round: series, frame, panel
• rename: series, frame, panel
• fillna: series, frame, panel
• reindex_axis: series, frame, panel
• dropna: series, frame, panel
• reindex: series, frame, panel
• transpose: frame, panel

I have expanded the signatures for:
reindex, rename, reindex_axis

I do not understand why round has the need for **kwargs (I read this http://book.pythontips.com/en/latest/args_and_kwargs.html at work this morning but I guess I have to read it again?). fillna seems to have the signature fully written. Similar question, why do we have **kwargs then?

dropna: series.py says that the doc-string is coming from generic.py ((@Appender(generic._shared_docs['to_excel'] % _shared_doc_kwargs)) but I searched in generic.py and I can only find the function drop. I don't know what to do about this one. dropna signature in frame.py and panel.py are different because frame.py has thresh=None

transpose: I don't know where the doc-string is coming from, so I did not edit it.

Any thoughts?

[jreback]

I do not understand why round has the need for **kwargs (I read this http://book.pythontips.com/en/latest/args_and_kwargs.html at work this morning but I guess I have to read it again?). fillna seems to have the signature fully written. Similar question, why do we have **kwargs then?

.round is a numpy method, so this is for compat (cc @gfyoung ), IOW np.round(series) needs to work (and it has other args).

[gfyoung]

Yes, that is correct. Annoying? Yes. Necessary? Debatable, but there was enough push early on from users for this to be implemented.

[jreback]

@PukkaPad btw, certainly ok to submit this in several PR's.

[MarianaBazely]

Ok, cool! I will submit the PR now - I will make the PR smaller next time if the commit is too big.

[VijayantSoni]

Hi @jreback , does this still need to be done ? I would like to take this on.

[dbalagula]

take

[dbalagula]

this should be closed, the issue is no longer there