Docstring fomatting

[jrcagle]

OK, this is a minor quibble from someone who is not *normally* concerned with neatness.

I want to put docstrings in my functions. If I put them in using the 'textbook' method:

def is_same(self,x):
        """A.is_same(x) --> Bool\n\nReturns True if A and x represent   
           essentially the same item, as determined by their userid.  Useful 
           for detecting undesired conflicts on lists that require unique 
           items."""

the code looks nice, but help(A.is_same) comes out as

>>>help(Account.is_same)

is_same(self, x) unbound __main__.Account method
    A.is_same(x) --> Bool
    
    Returns True if A and x represent essentially
               the same item, as determined by their userid.  Useful for 
               detecting undesired conflicts on lists that require unique 
               items.

which isn't terrible, but doesn't justify the paragraph correctly.

OTOH, I can write

def to_edit(self, new=False):
        "A.to_edit([new])--> (label,default)\n\nProduces a tuple for use \
by an Edit_Dialog.  The labels will be \ndisplayed by the Edit_Dialog, \
and the default will be used to fill in \nthe fields.  If new == True, \
None will be passed to Edit_Dialog."

which gives

>>>help(Account.is_same)

to_edit(self, new=False) unbound __main__.Account method
    A.to_edit([new])--> (label,default)
    
    Produces a tuple for use by an Edit_Dialog.  The labels will be 
    displayed by the Edit_Dialog, and the default will be used to fill in 
    the fields.  If new == True, None will be passed to Edit_Dialog.

So far, it seems that I'm forced to choose between readable docstrings and readable code. Anyone have a different solution?

Thanks,
Jeff

[vegaseat]

Python to the rescue ...

def test1():
    """In this documentation string
    the indentation becomes part of the string"""
    pass

print test1.__doc__
print

def test2():
    """
This is why Python relaxes the indentation rules
within a multiline string to allow this kind of
documentation string
    """
    pass

print test2.__doc__

[jrcagle]

OK, I feel dumb. Thanks! :cool:

P.S. How do you get the cool color options and such in your code snippets on this forum? I assume you don't code the HTML by hand...:)

[vegaseat]

The snippets code fields are highlighted by the website software. For regular threads you can use (php) tags instead of (code) tags to get php code highlighting. This does a good job with Python code, but there are some pitfalls! Like trailing \ are swallowed, and few other things! So fickle user beware!