[PYTHON DOC-SIG] doc string style question

[Ken Manheimer]

On Thu, 22 Aug 1996, Michael McLay wrote:

> My docstring style keeps dithering since I haven't found a well
> defined convention to follow.  Is there a WWW page on this that I've
> missed?   What's the recommended style for writting doc strings inside
> classes and function.  Here is a foo and a bar example that can be
> [...]
>
>    def barfunc(self):
>	 """barfunc definitions can often be longer than one line.
>	    Should they wrap and indent"""
>
>or 
>
>    def barfunc(self):
>	 """barfunc definitions can often be longer than one line.
>        Should they wrap and indent"""
>
> Opiniions?

Python-mode offers some good hints along these lines, and not just by
coincidence.  For instance, i much prefer the latter, and that is the
one "endorsed" by python-mode.  Python-mode represents deliberate
coding-style design decisions, with influence from guido as well as tim,
barry, and others.  Let the mode wrap the lines for you, and use Ctrl-j
when you specifically want to include a newline, or use Ctrl-i for
existing lines. 

(There are some things not conveyed by the mode, eg that the docstring's
first line ideally is a terse, self-contained description, with
subsequent lines after a blank line and elaborating; or where in general
to put blank lines, etc.  It would be really nice to develop an explicit
style guide, but that will take a volunteer to coordinate it...)

Ken Manheimer		klm@cnri.reston.va.us	    703 620-8990 x268
	    (orporation for National Research |nitiatives

	# If you appreciate Python, consider joining the PSA! #
		  # <http://www.python.org/psa/>. #


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================