#290 @return, @rtype notice warnings for property


here is a code:

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

    Edward Loper - 2008-08-24

    Logged In: YES
    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

  • Edward Loper

    Edward Loper - 2008-08-24
    • priority: 5 --> 4

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks