Python complaints

[skaller]

Charles Boncelet wrote:

> However there is nothing in the function declaration that specifies
> the type of its arguments.  In many cases, the way one finds out
> what types are allowed is by experimentation: call the function and
> see if you get an error.
> 
> E.g., the doc string for math.sin is "sin(x) return the sine of x".
> Nowhere does it tell me that "x" should be a number, not a list.

	Basically, the Python documentation is not yet
of Standards quality. It leaves a whole lot of issues unresolved.
But it is (now) not too bad.
 
> If Python is a typed language, shouldn't we be able to determine
> what types are allowed as arguments and returned from functions
> without experimentation (and reverse engineering from the source code)?

At least in part, the answer is that the developers continue
to use old fashioned technology instead of literate programming
tools. This makes it inconvenient to maintain documentation,
and leaves the developers with the mindset that documentation
is a separate task from programming.

Unfortunately, new technology supporting literate programming
is generally fairly arcane, hard to use, and slow
(and my literate programming tool, interscript, while
probably the best available tool, is no exception)

Python itself makes a small advance in this area (doc strings)
and Perl has POD (Plain Old Documentation). But the truth
is that no one really knows how to integrate documentation
and code in a reasonable manner.

-- 
John Skaller, mailto:skaller at maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia
homepage: http://www.maxtal.com.au/~skaller
voice: 61-2-9660-0850