[Python-Dev] Python Doc problems
fredrik at pythonware.com
Sun Oct 8 08:38:31 CEST 2006
> Plot a point at position x, y.
> 'x' - The x-coordinate.
> 'y' - The y-coordinate.
> void Plot( int x, int y );
> The scanner should note that: 'x' and 'y' are in single-quotes, so they
> probably refer to code identifiers.
or maybe they're string literals?
> The scanner can see that they are
> both parameters to the function, so there's no need to tell it that 'x'
> is an @param.
PythonDoc provides multiple parameter markers, so you can distinguish
between positional parameters and keyword arguments.
> In other words, the programmer should never have to type anything that
> can be deduced from looking at the code itself. And the reader shouldn't
> have to read a bunch of redundant information which they can easily see
> for themselves.
that's exactly why you need parameter markers in today's Python:
Python's function definition syntax doesn't allow the programmer
to fully communicate the intent behind the design.
(what's this post doing on python-dev, btw? should this discussion
take place on the doc-sig?)
More information about the Python-Dev