Re: python strings ( function func_doc strings )
Lars Wirzenius (wirzeniu@cc.helsinki.fi)
Wed, 27 Apr 1994 00:56:05 +0300
In article <9404261413.AA23849=guido@voorn.cwi.nl> you write:
> Steven D. Majewski:
> > > I would like to contradict myself (again) and AGAIN propose that an
> > > optional lisp-like doc-string syntax be added to the syntax for def
> > > ( and maybe lambda ) along with a new function attribute: func_doc,
> > > to hold that string.
>
> 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>
I'll begin by warning that I'm very, very new to Python. I haven't
even read the reference manual yet.
I do like the idea of documentation strings. However, I like
neither a nor b. a looks horrible for long strings, b seems
funny: why should a lone string at the beginning of the function
be different from a lone string anywhere else?
I'd do it like this, instead:
def foo(a, b):
doc: "here comes the description"
A new keyword (could be description instead of doc, for all I care)
adds the extra bit of hint to the reader.
Another thing (you're probably better off ignoring this): I didn't
see anything about assertations, yet (perhaps because I didn't read
the docs yet). If they're missing, I'd like to propose:
assert condition # abort program if condition is false
assert condition, str # ditto, but include str (an expression
# having string type) in the diagnostic
# message
In both cases, it would be nice to have a string representation of
the condition in the diagnostic message.
I'm not sure whether it is wise to let assertations be caught (except
as a command line flag to the interpreter). I'd rather not. An
AssertError exception might be preferable, though, if it fits better
to Python. I don't know. :-)
--
Lars.Wirzenius@helsinki.fi (finger wirzeniu@klaava.helsinki.fi)
My name is Ozymandias, king of kings/Look on my works, ye Mighty, and despair!