I see this attitude of "read the library source" most often from Ruby people, but some advocates of larger PHP frameworks advocate that approach as well, and I just don't buy it. At least, not across the board. Sure, if there's a bug, I can try to track it down, maybe submit a patch, but if something can't be bothered to be documented, I'm not sure I want to spend my time depending on that library.

I've certainly made exceptions to that - we probably all have - but treating that as the defacto way to approach using third party libraries is wholly inefficient (as you said).

One might take a better approach by saying "read and learn from the test cases". I've often found that for the libs I try that with, that have tests, they're often rather... what's the word? I can't easily figure out how to apply the library to the problem I have at hand. Sometimes it's because my problem is ill-defined, and sometimes it's because the tests only cover superficial cases, and even if the lib docs say "can do xyz", it's not tested not documented.

Such is software...