We're talking specifically about the point that there's a difference between API documentation (which should be an exaustive list of every function and the arguments it takes and why) and a tutorial that talks about how to use the thing. You're likely to find both in The Docs or they're simply not complete. And the point I was making was only that a techy will point out the difference or someone learning to program will quickly find the difference and then look for the tutorial first and the docs later when they're further along. That is the only point that I was making.
Everything else is a silly pointless argument. But this is the main takeaway: The Docs are almost always incomplete because there's nobody that's volunteered to write them and nobody paid to write them. What are you going to do? force the guy that volunteered to write the code to volunteer to write the docs? I doubt it's going to happen, so you'll have to live with reading source, writing your own, or using something else. If you lucked out and the dev wrote little blurbs above the function, great. If someone put some examples in a wiki, even better. If someone just happened to write geniuous docs, well, you've really found a gem and you're going to find a mix of tutorials and API docs and tutorials/examles for the good ones. The API docs are more important thouguh, cuz if all you have is some examples, you're going to go source diving without the API docs or you'll have to find something else.
PLUG IT IN!!!