Docstrings for `#[new]` method implementations

[davidhewitt]

Discussed in https://github.com/PyO3/pyo3/discussions/4280

^{Originally posted by **djc** June 23, 2024} When I write a docstring on a `#[new] fn new()` method in a `#[pymethods]` `impl` block, I would expect this to show up in the `help()` output for the type. Instead, the `help()` output seems to end up with a default docstring: ``` | Static methods defined here: | | __new__(*args, **kwargs) | Create and return a new object. See help(type) for accurate signature. ``` Is there no way in Python's data model to enable a specific help string for this? The docstring for the type ends up making it into the output sort of next to the constructor type signature, so I guess I could use that. Just seems surprising.

---

I believe that it should be possible to do something similar to what we already do with the text_signature for #[new] to lift the rest of the documentation onto the class. But this needs some experimentation.

[djc]

If you can give me a few pointers, I might be able to take a look myself.

[davidhewitt]

So changing the exact message Create and return a new object. See help(type) for accurate signature. is probably not possible. These all come from the type "slot wrappers" which take just a function pointer to the C slot implementation and then use that to generate a member on the class.

The one place where we can add class-level documentation is in the Py_tp_doc slot.

We already use pyo3::impl_::class::PyTypeImpl::doc to add the "text signature" from #[new] into the class-level documentation. We could similarly lift docs from #[new]. I think the only question is where in the class level documentation we should apply the docs from #[new], if adding this in is a good idea.

[jfolz]

Does this also affect other magic methods like __lt__? Regardless of what I write on the Rust side, its docstring is always "Return self<value."

[davidhewitt]

Yes, the same is true of these. I think the Python "slots" don't allow for documentation to be added, we would need to ask the CPython team for this.

[davidhewitt]

That said, there is METH_COEXIST which would allow us to install our own Python-level __lt__ (which could then have documentation). This would be a change to the proc-macros but might be a good thing. 🤔

[jfolz]

TBF though, I just check what help(set.__lt__) says:

__lt__(self, value, /) unbound builtins.set method
    Return self<value.

If set doesn't care to overwrite its docstring with a more sensible explanation, why should I care? :D