doc string substition and overloading __doc__ 
Author Message
 doc string substition and overloading __doc__

Suspect that this has been discussed before, but can't find a discussion.
The output of this script:

class klass1:
        """klass1"""

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

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

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

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

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

print klass1.__doc__
print klass2.__doc__
print klass3.__doc__
print def1.__doc__
print def2.__doc__
print def3.__doc__

Being:

klass1
None
klass3
def1
None
None

Raises a few questions in my mind about the string substition in doc
strings, the difference when overloading __doc__, and the difference in the
case of def.

Art



Wed, 19 Oct 2005 06:32:15 GMT  
 doc string substition and overloading __doc__

Quote:

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

Usual case, ok.

Quote:
> 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).

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

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

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

Usual case, ok.

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

Same as in klass2.

Quote:
> 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.



Wed, 19 Oct 2005 07:12:08 GMT  
 doc string substition and overloading __doc__
Quoth Fernando Perez:
  [...]

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

The assignment doesn't fail, silently or otherwise; it just isn't
run until the function is called, like any statement in a function
body.

    >>> def foo():
    ...     foo.__doc__ = 'Bar!'
    ...
    >>> foo.__doc__
    >>> foo()
    >>> foo.__doc__
    'Bar!'

--


                                                               "  (



Wed, 19 Oct 2005 08:16:21 GMT  
 doc string substition and overloading __doc__

Quote:

> Quoth Fernando Perez:
>   [...]
>> 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

> The assignment doesn't fail, silently or otherwise; it just isn't
> run until the function is called, like any statement in a function
> body.

>     >>> def foo():
>     ...     foo.__doc__ = 'Bar!'
>     ...
>     >>> foo.__doc__
>     >>> foo()
>     >>> foo.__doc__
>     'Bar!'

Thunk.  That was the sound of a slap on my own head :)  Thanks, it is, of
course, obvious.  

I should probably go for a beer instead of trying to code anymore.

Cheers,

f.



Wed, 19 Oct 2005 09:12:19 GMT  
 doc string substition and overloading __doc__
Fernando writes -

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

Which is in fact what I have in mind - i.e. it gets me to where I was
looking to get.

Art



Wed, 19 Oct 2005 22:55:59 GMT  
 
 [ 5 post ] 

 Relevant Pages 

1. Vds doc V5.3 ( To sell doc v5.3 )

2. Logo1.doc and Math1.doc in cyberspace

3. grafting DOM doc [as a fragment] into another DOM doc [node]

4. PROPOSAL: [].__doc__, "".__doc__, ...

5. Patches for tcl8.0/doc/* and tk8.0/doc/*

6. tcl8.0b1/doc and tk8.0b1/doc patches

7. [Doc-SIG] [development doc updates]

8. Write strings in a Word doc with presentation

9. pydoc string.find (doc bug/typo?)

10. language lawyering - doc strings

11. SWIG and __doc__ strings

12. Control of __doc__ strings

 

 
Powered by phpBB® Forum Software