Docstrings and class Attributes

[Terry Reedy]

On 8/8/2011 2:26 PM, Steven D'Aprano wrote:
> Eric Snow wrote:
>
>> On Mon, Aug 8, 2011 at 6:37 AM, Nick<nickle at gmail.com>  wrote:
>>> Is it possible to put a doc string on a class attribute?

This really makes little sense. The purpose of docstrings is to give 
interactive help. The place to document data attributes of a class is in 
the class docstring. The value of an int is considered to be 
self-explanatory.

>> You can put a docstring on a property (which is a function):
>>
>> class Test(object):
>>      @property
>>      def fred(self):
>>          "attribute"
>>          return 10
>
> Which, however, doesn't really help:
>
>>>> t = Test()
>>>> t.fred.__doc__
> 'int(x[, base]) ->  integer\n\nConvert a string or number to an integer ...'
>
>
> The problem is that t.fred returns an integer, so t.fred.__doc__ returns the
> docstring from the integer, not for the property.
>
>>>> t.__class__.fred.__doc__
> 'attribute'

Which is to say, the descriptor protocol allows custom get, set, and 
delete methods, but not an attribute-specific getattribute method ;-).

-- 
Terry Jan Reedy