[Python-checkins] python/nondist/peps pep-0257.txt,1.7,1.8

[goodger@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv17981/python/nondist/peps

Modified Files:
	pep-0257.txt 
Log Message:
Added "Handling Docstring Indentation" section.

Index: pep-0257.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0257.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** pep-0257.txt	28 Nov 2002 03:59:50 -0000	1.7
--- pep-0257.txt	30 Nov 2002 01:49:37 -0000	1.8
***************
*** 137,149 ****
  tools; it is important that it fits on one line and is separated from
  the rest of the docstring by a blank line.  The summary line may be on
! the same line as the opening quotes or on the next line.
! 
! The entire docstring is indented the same as the quotes at its first
! line (see example below).  Docstring processing tools will strip a
! uniform amount of indentation from the second and further lines of the
! docstring, equal to the minimum indentation of all non-blank lines
! after the first line of the docstring.  Relative indentation of later
! lines in the docstring is retained.  Any indentation on the first line
! of the docstring (i.e., before the first newline) is removed.
  
  Insert a blank line before and after all docstrings (one-line or
--- 137,143 ----
  tools; it is important that it fits on one line and is separated from
  the rest of the docstring by a blank line.  The summary line may be on
! the same line as the opening quotes or on the next line.  The entire
! docstring is indented the same as the quotes at its first line (see
! example below).
  
  Insert a blank line before and after all docstrings (one-line or
***************
*** 217,220 ****
--- 211,284 ----
  the closing quotes on a line by themselves.  This way, Emacs'
  ``fill-paragraph`` command can be used on it.
+ 
+ 
+ Handling Docstring Indentation
+ ------------------------------
+ 
+ Docstring processing tools will strip a uniform amount of indentation
+ from the second and further lines of the docstring, equal to the
+ minimum indentation of all non-blank lines after the first line.  Any
+ indentation in the first line of the docstring (i.e., up to the first
+ newline) is insignificant and removed.  Relative indentation of later
+ lines in the docstring is retained.  Blank lines should be removed
+ from the beginning and end of the docstring.
+ 
+ Since code is much more precise than words, here is an implementation
+ of the algorithm::
+ 
+     def trim(docstring):
+         if not docstring:
+             return ''
+         # Convert tabs to spaces (following the normal Python rules)
+         # and split into a list of lines:
+         lines = docstring.expandtabs().splitlines()
+         # Determine minimum indentation (first line doesn't count):
+         indent = sys.maxint
+         for line in lines[1:]:
+             stripped = line.lstrip()
+             if stripped:
+                 indent = min(indent, len(line) - len(stripped))
+         # Remove indentation (first line is special):
+         trimmed = [lines[0].strip()]
+         if indent < sys.maxint:
+             for line in lines[1:]:
+                 trimmed.append(line[indent:].rstrip())
+         # Strip off trailing and leading blank lines:
+         while trimmed and not trimmed[-1]:
+             trimmed.pop()
+         while trimmed and not trimmed[0]:
+             trimmed.pop(0)
+         # Return a single string:
+         return '\n'.join(trimmed)
+ 
+ The docstring in this example contains two newline characters and is
+ therefore 3 lines long.  The first and last lines are blank::
+ 
+     def foo():
+         """
+         This is the second line of the docstring.
+         """
+ 
+ To illustrate::
+ 
+     >>> print repr(foo.__doc__)
+     '\n    This is the second line of the docstring.\n    '
+     >>> foo.__doc__.splitlines()
+     ['', '    This is the second line of the docstring.', '    ']
+     >>> trim(foo.__doc__)
+     'This is the second line of the docstring.'
+ 
+ Once trimmed, these docstrings are equivalent::
+ 
+     def foo():
+         """A multi-line
+         docstring.
+         """
+ 
+     def bar():
+         """
+         A multi-line
+         docstring.
+         """