[Doc-SIG] Some random thoughts

[Laurence Tratt]

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/