DOC: defaults in method signature vs description

[kuraga]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Everywhere.

Documentation problem

The default value in method signature and the default value in the method description is sometimes different.
Examples:

https://pandas.pydata.org/docs/reference/api/pandas.Series.replace.html:
does Series.replace's:
to_replace have None (docs signature) as default, or have no default (docs description)?
value have no default (docs signature), or None (docs description)?

https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html:
does read_csv's:
sep have no default (docs signature), or ';' (docs description)?
...

...

Suggested fix for documentation

Fix.

[rhshadrach]

Thanks for the report!

Everywhere.

Rather that this, it would be helpful to compile a list of inaccuracies.

[rhshadrach]

As far as I know, we often use default None to mean unspecified. In the case of replace, specifying value=None is different from not specifying value at all. I don't see any instances where we have something like default <no_default>, which would perhaps be confusing. In my work, I've copied pandas' use of no_default but instead call it unspecified because of this reason.

@pandas-dev/pandas-core: any suggestions on how to document this better?

The sep argument of read_csv appears to be a more straightforward fix.

[WillAyd]

Conceptually these describe two different things - the signature shows the implementation whereas the docstrings describes the interface; while they usually align, that's not a hard requirement

Generally the no default sentinel is used when the value of None can be a legitimate argument (ex: wanting to actually fill an array with `None)

[kuraga]

There are three things then: the signature, the docstring signature, the docstring full description. Sure I was talking about the docs part.

[kuraga]

@rhshadrach , @WillAyd ,
let's synchronize.
Should be , default None added here?

[WillAyd]

Sure - feel free to push up any PRs for edits you see

[rhshadrach]

Somewhat tangential:

Generally the no default sentinel is used when the value of None can be a legitimate argument (ex: wanting to actually fill an array with `None)

We currently use either None or no_default for an argument that can't appear in the signature of a function.
Wouldn't push hard here, but it seems better to me to only use no_default for this purpose.