> ... document how a library is supposed to be used when they do exist ...
That will also depend on the library. In my library projects there is no way you'd figure out good/normal library usage because the vast majority of the test code is exploring edge cases and things that go wrong. I have 96-99% coverage which means there is a lot of non-normal usage tested. For example consider getting the length of something. Normal usage would just ask for it. Test code has to check different types, null pointers (if applicable), broken iterators, running out of memory and various other issues.
I do however have very comprehensive documentation including lots of example code. That of course is what the projects should provide rather than expecting reverse engineering of the test suite.
That will also depend on the library. In my library projects there is no way you'd figure out good/normal library usage because the vast majority of the test code is exploring edge cases and things that go wrong. I have 96-99% coverage which means there is a lot of non-normal usage tested. For example consider getting the length of something. Normal usage would just ask for it. Test code has to check different types, null pointers (if applicable), broken iterators, running out of memory and various other issues.
I do however have very comprehensive documentation including lots of example code. That of course is what the projects should provide rather than expecting reverse engineering of the test suite.