how to document a property

[Luis Zarrabeitia]

Quoting TP <Tribulations at Paralleles.invalid>:

> d  :
> int(x[, base]) -> integer
> 
> Convert a string or number to an integer, if possible.  A floating point
> argument will be truncated towards zero (this does not include a string
> representation of a floating point number!)  When converting a string, use
> the optional base.  It is an error to supply a base when converting a
> non-string. If the argument is outside the integer range a long object
> will be returned instead.
> [...]
> #######################
> 
> What is this default documentation?
> Why?

What you are reading is not the 'default documentation', but the documentation
for the 'int' type. Do help(5) and watch the result.

The problem is that when you do help(yourobj.d) you are not asking for the help
of the attribute named 'd' in yourobj. You are asking for the help of the object
that the attribute named 'd' is bound to at that point.

The same happens when you access help(yourobj.somefunction), with the only
difference that in that particular case, you have a chance to specify a
documentation for 'somefunction' and you are unlikely to change "somefunction"'s
binding at runtime.

So if you need to do something like:

[warning: syntax is not valid]

class A(object):
    age = 0 "stores the age of the person" #invalid syntax warning
    def blablah(self): pass

a = A()
help(a.age)
a.age=7
help(a.age)

and always get "stores the age of the person", I don't think python has any
syntactical way of doing that. You could simulate it using properties, though
(do a 'help(property)' to see an example), but I'm not sure if that will be a
good solution.


-- 
Luis Zarrabeitia
Facultad de Matemática y Computación, UH
http://profesores.matcom.uh.cu/~kyrie