[Python-Dev] Best way to specify docstrings for member objects

[Raymond Hettinger]

> 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