Multi-line docstrings

[Lawrence D'Oliveiro]

The Python docs recommend the use of triple-quoted string literals for
docstrings, e.g.

def Meet(Alice, Bob) :
"""arranges a meeting between Alice and Bob.
Returns a reference to the meeting booking object."""
...
#end Meet

However, these tend to get messed up by indentation whitespace, which gets
spuriously included as part of the string.

Another possibility is to use implicit concatenation of string literals,
e.g.

def Meet(Alice, Bob) :
"arranges a meeting between Alice and Bob." \
" Returns a reference to the meeting booking object."
...
#end Meet

This includes no spurious whitespace, or even any newlines; if you want
these, you must put them explicitly in the string:

def Meet(Alice, Bob) :
"arranges a meeting between Alice and Bob.\n" \
"Returns a reference to the meeting booking object."
...
#end Meet

 

[Duncan Booth]

The Python docs recommend the use of triple-quoted string literals for
docstrings, e.g.

def Meet(Alice, Bob) :
"""arranges a meeting between Alice and Bob.
Returns a reference to the meeting booking object."""
...
#end Meet
However, these tend to get messed up by indentation whitespace, which
gets spuriously included as part of the string.

Not spuriously included: included by design, but sometimes annoying. If you
are just printing __doc__ in interactive mode then live with the extra
whitespace. If you are printing out lots of docstrings as part of some
documentation tool then use textwrap.dedent to remove the common leading
spaces.

Another possibility is to use implicit concatenation of string
literals, e.g.

This includes no spurious whitespace, or even any newlines; if you
want these, you must put them explicitly in the string:

<snip>

.... which is why the triple-quoted format is recommended. BTW, you missed
this way of doing it which ensures that all lines, even the first one have
the same indentation (and therefore textwrap.dedent will strip it quite
nicely):

def Meet(Alice, Bob) :
'''\
arranges a meeting between Alice and Bob.
Returns a reference to the meeting booking object.
'''

and if you want to do string concatenation you can always get rid of those
pesky backslashes:

def Meet(Alice, Bob) :
("arranges a meeting between Alice and Bob.\n"
"Returns a reference to the meeting booking object.")

 

[bearophileHUGS]

Duncan Booth:

Not spuriously included: included by design, but sometimes annoying.

Then it's a design decision I don't understand...

Bye,
bearophile

 

[Duncan Booth]

Duncan Booth:

Then it's a design decision I don't understand...

I think the decision is that the doc string should reflect exactly what you
entered in the string. i.e. the system shouldn't tamper with it behind the
scenes.

 

[Lawrence D'Oliveiro]

Not spuriously included: included by design, but sometimes annoying.

The problem is that the treatment of indentation whitespace in triple-quoted
strings is at odds with its use for syntax purposes elsewhere in the
language.

Instead of preserving all included whitespace, a better rule for
triple-quoted strings might be to strip whitespace up to the current
indentation level from each continuation line. That is, each line _must_
begin with at least that amount of whitespace, otherwise it's an error; any
extra whitespace is preserved. E.g.

a = """two lines
of text"""

being equivalent to

a = "two lines\n of text"

Or, a simpler rule might be to strip _all_ whitespace at the start of each
continuation line, regardless of indentation level. So the triple-quoted
example above becomes equivalent to

a = "two lines\nof text"

If you _want_ to include some whitespace at the start of a continuation
line, simply precede it by something that isn't literal whitespace:

a = """two lines
\x20 of text"""

becomes equivalent to

a = "two lines\n of text"

(It might be nice if "\ " was recognized as equivalent to "\x20" for this
purpose.)