Donald Beaudry:
> This, or even somthing resembling it gets a YES vote from me.
>
> I particularly like the what emacs does.
>
> (For the emacs challanged: The first sentence of the paragraph is
> supposed to be a short one-line description of the function and rest
> of the paragraph describes the function in more detail. The first
> sentence, along with the function name is then used to build a data
> base which can be searched. The search returns the the function name
> and the first sentence. The entire doc string can obtained once the
> function name is known.)
I also like this kind of form of documententation. I am currently
dithering between two forms of syntax:
(a)
def square(a) "compute the square of a number" :
return a*a
(b)
def square(a):
"compute the square of a number"
return a*a
I have a feeling that (b) looks slightly better, especially in the
case of a longer documentation string, e.g.
(a)
def system(s) """send a command to the shell
This forks a child process which execs /bin/sh.
The parent waits until the child exits or dies.
The return value is either:
256 times the child's exit code (if it exits)
the signal number plus 128 (if it dies)
127 (if the fork or exec fails)
""":
pid = os.fork()
if pid: return os.waitpid(pid, 0)[1]
os.execv('/bin/sh', ['sh', '-c', s])
versus
(b)
def system(s):
"""send a command to the shell
This forks a child process which execs /bin/sh.
The parent waits until the child exits or dies.
The return value is either:
256 times the child's exit code (if it exits)
the signal number plus 128 (if it dies)
127 (if the fork or exec fails)
"""
pid = os.fork()
if pid: return os.waitpid(pid, 0)[1]
os.execv('/bin/sh', ['sh', '-c', s])
Note that (b) will require me to fix printing of expressions
(otherwise there would be some kind of ambiguity) -- but I was going
to do that anyway.
OTOH, that particular fix probably won't find its way into 1.0.2,
while the required patch for option (a) would probably be less than 10
lines...
--Guido van Rossum, CWI, Amsterdam <Guido.van.Rossum@cwi.nl>
URL: <http://www.cwi.nl/cwi/people/Guido.van.Rossum.html>