[Python-Dev] Documentation idea
doug.hellmann at gmail.com
Thu Oct 16 23:28:01 CEST 2008
On Oct 16, 2008, at 5:11 PM, Raymond Hettinger wrote:
>> Raymond Hettinger wrote:
>>> * It will assist pypy style projects and other python
>>> when they have to build equivalents to CPython.
>>> * Will eliminate confusion about what functions were exactly
>>> intended to
>>> * Will confer benefits similar to test driven development where the
>>> documentation and pure python version are developed first and
>>> 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
>> 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
> 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
> Running both sets of test should suffice to maintain the rough
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
More information about the Python-Dev