[Doc-SIG] Some random thoughts
Laurence Tratt
laurie@eh.org
Sun, 05 Mar 2000 21:43:59 GMT
In message <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>
Ka-Ping Yee <ping@lfw.org> wrote:
>> Here are some things that tend to cause complications in current doc
>> strings:
>>
>> * Many look like:
>>
>> def __init__(self):
>> """The first line
>>
>> The rest of the body
>>
>> Blah blah
>> """
>>
>> What exactly is the indentation of that whole thing? To the human eye
>> the answer is 8. In my implementation the above *doesn't* do what you
>> expect because the first line gets an indentation of 0 and the rest
>> an indentation of 8 (meaning the body is a sub paragraph of the rest):
> I came across this problem too. "manpy"'s solution to this problem
> is to look for the minimum indentation of all lines except the first,
> and remove that amount of indentation from all the lines in the string.
>
> More compactly stated,
>
> lines = split(expandtabs(docstring), "\n")
> margin = min(map(lambda line: len(line) - len(lstrip(line)), lines[1:]))
> for i in range(1, len(lines)): lines[i] = lines[i][margin:]
>
> It does make assumptions, but it's always done the right thing so far.
I nearly did that, but my personal preference is to cut down on these sorts
of assumptions where possible. My thinking was (without wishing to start a
flame war), this sort of auto-pseudo-intelligence is quite Perl like and
tends to lead one into troubles in the future when one finds a need to break
the assumption to allow something else to work...
From an aesthetics point of view, I actually find:
"""
The first line
The main body
"""
clearer than:
"""The first line
The main body
"""
or:
"""The first line
The main body"""
you-win-some-you-lose-some-it's-much-the-same-to-me-ly y'rs Laurie
--
http://eh.org/~laurie/comp/python/