[Doc-SIG] suggestions for a PEP
Edward D. Loper
edloper@gradient.cis.upenn.edu
Thu, 15 Mar 2001 19:29:01 EST
> > I didn't think this was possible, because the following fails::
> >
> > B.f.__doc__ = A.f.__doc__
> >
> > But really you have to do this:
> >
> > B.f.im_func.__doc__ = A.f.__doc__
>
> erm ...
...
> 'hello there'
>
> if it fails in 2.*, eek !
The problem is that A.f is a method, not a function::
>>> type(A.f)
<type 'instance method'>
>>> type(A.f.im_func)
<type 'function'>
>>>
And when you read A.f.__doc__, some "magic" returns A.f.im_func.__doc__.
But there isn't really an A.f.__doc__. But as long as you change
A.f.im_func.__doc__, the changes will be visible from A.f.__doc__::
>>> A.f.im_func.__doc__ = "new doc"
>>> A.f.__doc__
'new doc'
So.. it may make sense to somehow change the magic that associates
a method with it's functions documentation.. But it's not a serious
problem, because you *can* set the docs of a module.
I don't really know what "acquisition" is, but one problem with making
this an automatic process is that sometimes it's *not* what you
want. I guess the question is whether it's what you want more often
or not what you want more often. If it's usually what you want,
you can disable it with::
class B(A):
def f(x):
"" # don't inherit docs
return x+1
If it's usually *not* what you want, or if we want to keep things
simpler, the following seems to work (I don't know why you don't
need to use .im_func here)::
class B(A):
def f(x):
return x+1
B.f.__doc__ = A.f.__doc__
I'd be happy with either.
-Edward