[Python-Dev] Documentation idea

[Doug Hellmann]

On Oct 16, 2008, at 5:11 PM, Raymond Hettinger wrote:

>> 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*?
>
> Glad you brought this up.  My idea is to present rough equivalence
> in unoptimized python that is simple and clear.  The goal is to  
> provide
> better documentation where code is more precise than English prose.
> That being said, some subset of the existing tests should be runnable
> against the rough equivalent and the python code should incorporate  
> doctests.
> Running both sets of test should suffice to maintain the rough  
> equivalence.

This seems like a large undertaking.  I'm sure you're not  
underestimating the effort, but I have the sense that you may be  
overestimating the usefulness of the results (or maybe I'm  
underestimating them through some lack of understanding).  Would it be  
more optimal (in terms of both effort and results) to extend the  
existing documentation and/or docstrings with examples that use all of  
the functions so developers can see how to call them and what results  
to expect?

Doug