If you're looking for a great counter-example of how to document something see any boost library. It's amazing to me how often their documentation and reference material fails to answer the most simple of questions.
Today's problem? I have managed to find the exact documentation for the function that I want to use. That documentation is lacking the following super-critical information for a library this large and complicated:
It's amazing that we ever manage to write anything in this language.
We come here in search of a place to express our thoughts outside of the direct control and surveillance of unaccountable, mega-corporations. There is no common theme that binds us other than these being the bonds we've chosen rather than those that have been chosen for us.