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

[MRAB]

On 2019-03-19 18:55, Raymond Hettinger wrote:
> I'm working on ways to make improve help() by giving docstrings to member objects.
> 
> One way to do it is to wait until after the class definition and then make individual, direct assignments to __doc__ attributes.This way widely the separates docstrings from their initial __slots__ definition.   Working downstream from the class definition feels awkward and doesn't look pretty.
> 
> There's another way I would like to propose¹.  The __slots__ definition already works with any iterable including a dictionary (the dict values are ignored), so we could use the values for the  docstrings.
> 
> This keeps all the relevant information in one place (much like we already do with property() objects).  This way already works, we just need a few lines in pydoc to check to see if a dict if present.  This way also looks pretty and doesn't feel awkward.
> 
> I've included worked out examples below.  What do you all think about the proposal?
> 
[snip]

Thinking ahead, could there ever be anything else that you might want 
also to attach to member objects?

I suppose that if that's ever the case, the value could itself be 
expanded to be a dict, something like this:

__slots__ = {'mu' : {'__doc__': 'Arithmetic mean.'}, 'sigma': 
{'__doc__': 'Standard deviation.'}}

But that could be left to the future...