What do you consider good API documentation?

I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?

Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.

A good documentation MUST have:

• datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
• function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
• an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
• examples. Sometimes they are more important than all the rest

I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...

Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?

What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.

Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:

• Very easy jump to docs from the API.

• Well formatted and the code snippets you would want to copy and paste (like method signatures) stand out.

• Links to projects with sample code right from the docs.

• Automated document refresh mechanism, but by default docs are all local to start (so you can live with a flaky internet connection).

• Easy way to switch between variants of documentation (to see different versions of the OS), and also select which sets of documentation to run searches against.

• An overview section explains what the class is for, followed by a section breaking out methods grouped by purpose (methods to create and object, methods to query for data, methods to work with type conversions, etc), followed by the detailed method explanations.

I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.