doc string substition and overloading __doc__

[Fernando Perez]

Arthur wrote:


> class klass1:
>         """klass1"""

Usual case, ok.

> class klass2:
>           """%s""" %'klass2'

The first statement in the class is NOT a simple string, it's a string
interpolation.  Hence, __doc__ is None (as per the language's definition).

> class klass3:
>         __doc__ = """%s""" %'klass3'

Explicit assignment to __doc__, which becomes a class attribute as it
should.

> def def1():
>         """def1"""

Usual case, ok.

> def def2():
>          """%s""" %'def2'

Same as in klass2.

> def def3():
>          __doc__ = """%s""" %'def3'

__doc__ is a local in def3's scope, NOT an _attribute_ of def3.  So once you
are out of def3's scope, you can't see it.  That's as it should be.

What you have in mind, assigning to an _attribute_ of def3, is accomplished
via:
In [2]: def def3():
   ...:     pass
   ...:

In [3]: def3.__doc__ = """%s""" % 'def3'

In [4]: pdoc def3
def3

Note that, in a quirk of counter-intuitiveness, the following code is
accepted but the assignment fails silently.  This one I'd call a wart, at
least:

In [5]: def def3():
   ...:     def3.__doc__ = 'hi'
   ...:

In [6]: pdoc def3
No documentation found for def3

Cheers,

f.