[DOC-SIG] docstrings for args

[Fred L. Drake]

Paul Prescod writes:
 > Would it be useful to be able to do this:
 > 
 > def open( file		"The filename",
 >           mode="r" 	"The mode" ):
		  ^^^^^^^^^^^^^^^^

  This is equivalent to mode="rThe mode" due to the string catenation
rule.  Some other form of separation would be necessary.
  A few sets of conventions exist for formatting the docstring such
that it can be picked apart.  I think Guido suggested most recently:

	def open(file, mode="r"):
	    """A short synopsis first.

	    file -- The filename
	    mode -- The mode

	    More descriptive text here...."""

  This is fairly readable and can be dealt with fairly easily by an
automatic extractor.  I have a class that parses docstrings like this; 
I'll try and clean up a few rough edges and document it over the next
day or two.


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

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