#290 @return, @rtype notice warnings for property

v3.0
open
nobody
4
2008-08-24
2008-08-24
bart skowron
No

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.

Discussion

  • Edward Loper
    Edward Loper
    2008-08-24

    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
    """)

     
  • Edward Loper
    Edward Loper
    2008-08-24

    • priority: 5 --> 4