[Python-Dev] Documentation idea

[Scott Dial]

Raymond Hettinger wrote:
> * It will assist pypy style projects and other python implementations
> when they have to build equivalents to CPython.
> 
> * Will eliminate confusion about what functions were exactly intended to
> do.
> 
> * Will confer benefits similar to test driven development where the
> documentation and  pure python version are developed first and doctests
> gotten to pass, then the C version is created to match.

I haven't seen anyone comment about this assertion of "equivalence".
Doesn't it strike you as difficult to maintain *two* versions of every
function, and ensure they match *exactly*? The utility to PyPy-style
projects is minimized if the two version aren't identical. And while
it's possible to say, "the tests say they are equiavelent, so they are;"
history is quite clear about people depending on "features" that are
untested and were unintended side-effects of the manner in which
something was implemented. I think it would be a dilution of developer
man-hours to force them to maintain two versions in lock-step, and it
significantly adds to the burden of writing and reviewing potential
bugfixes.

While I applaud the idea of documenting C functions in this manner,
let's not confuse documentation with equivalence. If the standard
distribution of Python exports the C version, then all bets are off
whether the Python version is a drop-in replacement (even if the
buildbots regularly test them). I feel so strongly about this that I
think that the consideration of adding this should be frame /solely/ as
a documentation tool and nothing more.

-Scott

-- 
Scott Dial
scott at scottdial.com
scodial at cs.indiana.edu