DOC: `name` in `Index.to_frame` is claimed to default to `index.name`

[cmp0xff]

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

https://pandas.pydata.org/docs/dev/reference/api/pandas.Index.to_frame.html

Documentation problem

The actual default value is lib.no_default, but the docstring says name : object, defaults to index.name

Suggested fix for documentation

Change to something like name : Hashable, defaults to lib.no_default and move self.name to the next line, in the description. (object to hashable if the name is required to be a hashable)

[rhshadrach]

When not specified, you get index.name. What is the problem with the documentation?

[cmp0xff]

I think what was implied was that pandas internally uses the value of index.name when name is unspecified. But name itself defaults to lib.no_default, which is a technical thing.

[rhshadrach]

The default is what happens when you leave the argument unspecified. I think this is fine.

[cmp0xff]

What I understood as defaults to is being the default argument. The current description seems to be literally foo(self, name: Hashable = self.name) to me.

I would prefer to write something more descriptive and less technical like name : Hashable, uses self.name if not provided.

I won't insist further, but it would be great if we got a third pair of eyes on the current issue.

[bilalr-dev]

Use wording that describes behavior without implying the parameter default, for instance:
name : Hashable, uses ``self.name`` if not provided
or

name : Hashable, default lib.no_default
    Name for the column. Uses ``self.name`` if not provided.

i think first option is perfect, it’s clear, accurate, and avoids implementation details while still being informative