[docs] [issue27043] Describe what ‘inspect.cleandoc’ does to synopsis line.

[Nathan Harold]

Nathan Harold added the comment:

Here's my shot at a revision (corresponding patch attached):

   Clean up indentation from docstrings that are indented to line up with blocks
   of code.  All leading whitespace is removed from the first line.  Any leading
   whitespace that can be uniformly removed from the second line onwards is
   removed.  Empty lines at the beginning and end are subsequently removed.  Also,
   all tabs are expanded to spaces.

This version also makes it explicit that nothing happens to trailing whitespace, should a line happen to have any.  This actually seems to be a difference between this function and the sample implementation in the PEP.

One odd side effect of that difference is that a line consisting only of whitespace may actually not be removed from the beginning or end of the string, if the preceding whitespace removals aren't sufficient to leave the line completely empty.  For instance:

>>> inspect.cleandoc('   A \n  B \n   \n  ')
'A \nB \n '

Two spaces are removed from each of the second, third, and fourth lines.  The fourth line is then empty and is removed; the third line still contains one space and is kept.

On the other hand, as defined in the PEP, the extra space on the third line is removed as trailing whitespace, so that the third line is then removed entirely:

>>> trim('   A \n  B \n   \n  ')
'A\nB'

Most likely this difference rarely affects anything.  In any case, mentioning it here because it influenced exactly how I revised the docs.

----------
keywords: +patch
nosy: +nharold
Added file: http://bugs.python.org/file43018/cleandoc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27043>
_______________________________________