I'm sure I'll be in the minority here, but a huge benefit of using libraries is that I don't have to know how they work, or care. The documentation says 'call foo() with this argument to do bar', and that's all I want to care about.
I have other things to worry about (like my own code), than to want to dig into the internals of somebody's else's library to figure out something which should be easily documented.
I see the benefit of a library as being that I don't need to write the code, but it still won't go in one of my projects until I understand what it does and whether it actually works the way it should. Personally, I encounter bugs and bad code in libraries all the time, especially in libraries that extend or hook into web frameworks.
I could see that working in web frameworks, where the library code is often doing something vaguely similar to the application code. I'm not sure how well it translates out of that scene, though. Am I really supposed to be reading the GNU libc source in order to debug my problem? Or the LAPACK source? It can occasionally help, but much of the time it won't. Do you really understand how all those libraries operate? Should you have to?
I mean, even with web frameworks you could take this to the next level. Want to know how a bit of CSS works? Don't read the HTML5 docs--- just dig right into the Firefox and Chromium codebases to see what browsers actually do with it.
Ironically, LAPACK is for the most part pretty straight forward. Most of the code is simply shells out to BLAS routines. Because everything is matrix-matrix, it all maps reasonably well to how you'd explain it in a math textbook.
Also, the documentation tells you what is intended to be public, stable API, vs. what's an implementation detail that may change with the next release.
Anyway, I used to work like this, but a couple years ago I just said "screw it" and started diving in and reading the source for libraries that I use. And that's been a very good decision so far. Using only libraries that are well-documented sets a ceiling on what you can accomplish, and hence makes your software less impressive and your potential rewards much lower. Everybody else can Google the web and read the docs; relatively few people are willing to dive into the source and understand how the library really works. The way to distinguish yourself from those people is to do what they're not willing to, and work on the hard stuff.
Some libraries are poorly documented because their authors are lazy, but many more are poorly documented because their authors are working on hard problems. If you leverage their work, even though it's not easy, you can work on hard problems too, and that's where most of the rewards are.
I'm currently doing a lot of stuff with LLVM. LLVM is actually fairly well-documented for an open-source project: there's at least a bunch of tutorials and Doxygen. Despite this, there've still been a bunch of times I've had to go back to the source. I had to hunt around to figure out how to disable the default dlsym() behavior and explicitly expose all functions I want the compiled code to be able to access. And then I found this didn't work when I statically linked the binary; I had to ask a coworker who's a dev on the project what was up, and it turned out it was a bug in the compiler framework.
For my startup, I was doing a bunch with mtasc and swfmill. Beyond basic command-line options, there's pretty much no reference for how to put these together to generate a Flash file of moderate complexity. I basically just tried things that sorta looked like the demo examples, and permuted them until they worked.
A few years back, I did a bunch with Netbeans. I had to look at the source code for virtually everything. I had to manually trace back deadlocks by seeing which framework code was holding which monitors. I had to grep the codebase to figure out which Lookup file a particular extension point was checking. Most of the APIs, I just had to try and see whether they did with I want.
Usually, the only open-source libraries that work smoothly are the ones that lots of people are already using. They got that way because the early adopters put up with a bunch of pain and contributed back to fixing the problems they encountered. If you're fine with trailing the pack, you can rely on the documentation. But if you're going to lead the pack, you often have to write the documentation.
Seriously, a 'library' can be anything, from a standard, well document library that comes with the OS, to a chunk of code you got from a coworker. No all of them will have documentation, and then even if you have it it's often the case that the documentation is not 100% correct or up to date.
The trouble is that this behavior swaps over. I often see people on IRC googled for an answer, but would have never thought about looking at the nice, shipped, and even installed documentation.
I definitely feel the opposite. While there is a lot of crappy code out there, if you look, you can also find a lot of good code, which you can learn from.
Ruby code usually has the rdoc-style comments right above the method definition, and not all of those explanations make it to the README...
I did this yesterday. The README of Authlogic doesn't cover using a single access token to log in without a username or password, but the comments in the code does:
Love authlogic; it's such a well-constructed library. Just the other day I borrowed the method they use for getting access to controller functionality like cookies and params. It's the sort of thing I've always done by passing the controller object to the method that needs it, but the authlogic way is just so much cleaner: http://github.com/binarylogic/authlogic/blob/master/lib/auth...
