[Python-Dev] Python Doc problems (original) (raw)

Fredrik Lundh fredrik at pythonware.com
Sun Oct 8 08:38:31 CEST 2006

Talin wrote:

/* 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 mailing list