Python documentation annoyance

Edit: I've actually started working on fixing this annoyance in Python. See Python issue 9264.

Edit 2: my patches to the documentation were all committed and issue 9264 has been closed. No more annoyance :-)

I love Python, but the documentation of its standard library (or the lack thereof) is sometimes annoying. Python's "batteries included" approach is good, but sometimes modules get into the library without proper quality assurance. And quality is not only the correct workings of the code, but also the level of its documentation.

For example, today I wanted to use the trace module. The Python 2.5.2 documentation installed on my workstation has very scarce documentation, so I thought that it has perhaps been fixed in 2.6, but alas, no.

The documentation of the programming interface of trace is minimal, and most important options aren't documented at all. The single existing example is trivial and definitely inadequate for understanding what the module can do.

So, once again I go to the Python installation and read the module's code. Luckily Python is the most readable programming language one can think of, so the module's code can be easily understood. But this, naturally, isn't the right way to do it.