Jonathan M Davis:
I confess that my initial reaction is that it's incredibly messy to have user comments on documentation. It seems unprofessional to me, and if the documentation isn't adequate, then I'd argue that it should be improved rather than having stray users comment on it. This is API documentation, not a blog.
The PyGame documentation (http://www.pygame.org/docs/ref/draw.html ) divides the documentation in two parts, the professional serious part, and the user comments. Sometimes user comments are like a staging to later become parts of the official documentation. User comments are useful for example usages.
Bye, bearophile
