Message 257485 - Python tracker

Agreed that improving the docs doesn't belong in this bug, but in general
if the docs aren't clear enough and only a visit to the source helps you
understand, something's wrong. Because the source may do things one way
today and be changed to do things differently tomorrow, all within the
(intended) promises of the API. But without docs we don't know what those
promises are.