[Python-Dev] Best way to specify docstrings for member objects (original) (raw)

Raymond Hettinger raymond.hettinger at gmail.com
Wed Mar 20 18:53:26 EDT 2019

On Mar 20, 2019, at 3:30 PM, Gregory P. Smith <greg at krypto.org> wrote:

I like the idea of documenting attributes, but we shouldn't force the user to use slots as that has significant side effects and is rarely something people should bother to use.

Member objects are like property objects in that they exist at the class level and show up in the help whether you want them to or not. AFAICT, they are the only such objects to not have a way to attach docstrings.

For instance level attributes created by init, the usual way to document them is in either the class docstring or the init docstring. This is because they don't actually exist until init is run.

No one is forcing anyone to use slots. I'm just proposing that for classes that do use them that there is currently no way to annotate them like we do for property objects (which people aren't being forced to use either). The goal is to make help() better for whatever people are currently doing. That shouldn't be controversial.

Someone not liking or recommending slots is quite different from not wanting them documented. In the examples I posted (taken from the standard library), the help() is clearly better with the annotations than without.

Raymond

More information about the Python-Dev mailing list