#290 @return, @rtype notice warnings for property

[bart skowron]

here is a code:
#!python

class C(object):
def _g(self):
"""
something here

@rtype: C{int}
@return: blabla
"""

return 0

g = property(_g)

obj = C()
print obj.g

x@banan:~$ epydoc kili.py -v
+----------------------------------------------------------------------------------------------
| File /home/x/kili.py, in kili.C.g
| Warning: Invalid context for u'rtype'
| Warning: Invalid context for u'return'

the same code without the line g = property(_g) works fine.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

Yeah, a change was made in a recent version of python (don't remember which one) where a property's docstring will default to the docstring of its getter function if no docstring is explicitly specified for the property. I.e., if you import kili and print kili.C.g.__doc__ in your example, you'll get the docstring that you defined for kili.C._g().

This has always seemed like the wrong thing to do to me -- a description of a getter function is not the same as a description of a property -- but I can understand why it was done.

Epydoc should probably be modified to deal with this case. Handling the "@rtype" field is simple enough -- just use it for the property's "@type" field. It's a little less clear how the "@return" field should be handled -- should it be used instead of the function description, or combined with it somehow?

So I agree that this is something that should be dealt with, but I probably won't have time to fix it myself for a while.

A work-around is to define an explicit docstring for your property, which will prevent python from copying the docstring from the getter function. E.g.:

g = property(_g, doc="""
The glowing green apple belonging to this C object (read-only).
@type: fruit
""")