[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

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