[Python-Dev] Documentation idea

[Raymond Hettinger]

From: "Doug Hellmann" <doug.hellmann at gmail.com
> This seems like a large undertaking.

Not necessarily.  It can be done incrementally, starting with things like str.split() that almost no one understands completely.  It 
should be put here and there where it adds some clarity.


> 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?

The idea includes pure python code augmented by doctestable doctrings
with enough examples.  So, we're almost talking about the same thing.
There is one difference; since the new attribute is guaranteed to be
executable, it can be reliably run through doctest.  The same is *not* true
for arbitrary docstrings.


Raymond