[DOC-SIG] doc strings

[Edward Welbourne]

OK, I accept that it's better to stick with the gendoc `structured text'
approach rather than using *ML, TIM or anything else in python doc
folds, even if that does mean I've now got a fair slice of HTML to
retro-convert in existing code.  I'll come back (if I remember) to how
we might be able to improve on this ...

First off, I want the doc string extractor to be able to decipher `type'
and `default' information from the centre-piece of every doc string I've
written - the argument list.  Example (in gendoc's form):

Arguments:
 file -- file-name string.  The name of the file to open.

 [mode] -- ('r') I/O mode string.  ...

 [bufsiz] -- (-1) integer.  Buffer size to use for I/O, if bufsize >
 1: a value of 1 requests line buffering, 0 requests unbuffered I/O and
 any negative value requests the implementation's default.

It might be worth recognising the word `argument' or `arguments', along
similar lines to `example', if we can think of a common format for
`default and type' information, possibly exploiting the fact that this
will take the form of the list item's first `sentence'.  If default is
there, it's the first thing after -- and is enclosed in ().  Next comes
type information, up to `end of sentence'.  The rest of the paragraph
might be worth typesetting as a separate paragraph in the <DD>, as if
(in the HTML output to be generated from the above)

<P>Arguments:</P><DL>
<DT>file<DD> file-name string. <P> The name of the file to
open. </P></DD>
...
</DL>

Note that if -- is followed by (...) and ... happens to contain a match
to the pattern being used to detect `end of sentence', it shouldn't be
counted as such because it's inside the default spec.


Here's another sample of a docstring (gde.process.execute.__doc__,
wrapping os.execv and os.execve up) to illustrate use of gendoc's
`structured text' for the uninitiated.  Note that the method's name and
the fact that it's a method (of a class called gde._Process, as it
happens, but it should be documented as a method of the value
gde.process) can be extracted by the tools which crawl over the
namespace digging out the doc-strings and gluing them together.  Note
that the method also has a `self' argument which doesn't appear here.

"""Replaces the current process.

Required argument, file, is the pathname of a file, which must be
executable, to be executed.  The resulting process will replace the
current process.  Optional arguments:

 args -- ([]) list of strings.  The arguments to be passed to file.

 env -- (None) dictionary, mapping strings to strings.  If omitted (or
 given as None), the new process will run in the same environment as the
 old one; otherwise, env gives the environment in which the new process
 is to run.

*Does not return.*"""

	Eddy.

_______________
DOC-SIG  - SIG for the Python Documentation Project

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