Re: python strings ( function func_doc strings )

Steven D. Majewski (sdm7g@elvis.med.virginia.edu)
Tue, 26 Apr 1994 11:21:10 -0400

On Apr 26, 16:13, Guido.van.Rossum@cwi.nl wrote:
>
> 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.
>

I also like the looks of (b), but I didn't suggest it because, right
now, ( using def (b) ):

>>> square(4) # prints
'compute the square of a number'
16
>>>

>
> 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.
>

Oops! Did I miss something? Are you planning to get rid of printing
of (unassigned) expressions TOTALLY ? - I thought it was going to be
a command line option. ( Or am I misunderstanding you? )

>
> 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...
>

That is the other reason I suggested (a).
However, I would not dismiss a better syntax because the other was
somewhat easier to implement - we will have to live with this syntax
for a while, so it's worth while to do it right.
The real objection to (b) is that it already means something else!

- Steve Majewski (804-982-0831) <sdm7g@Virginia.EDU>
- UVA Department of Molecular Physiology and Biological Physics