What are the best ways that you have found to document the use of an API?
Comments on classes and methods, such as JavaDoc comments, are useful for learning about how a particular class or method works, but I'm asking about how people document higher-level concepts that show how to actually use the API.
Comments that include code samples are often too buried to be findable or useful. External documentation quickly gets out of date.
Code samples withing JavaDoc (or Doxygen) are what I've found to work best. Basically, take your simplest test code for the method and shove it into the doc. The sample is with the method it tests so it is easy to find, and it should be pretty simple to keep up to date.
One of the best documented products out there is Django in my opinion. Its documentation is very easy to look through, and well written. It has a kind of wiki feel to it. It should be noted that it does not appear to be generated from comments/auto-documenting; it was written separately for the sole purpose of documenting how to use the platform.
Another good one is MSDN, though sometimes it feels a little lightweight in terms of examples and such..
For example's of good api documentation look at the Mashery's customers sites. All of these are built using the tools Mashery offer, I have not used them directly so I can't offer any comment on how they work but the documentation they produce tends to be of a good standard.
Good unit tests can provide a good reference for how to use the API. It also has an added bonus of testing your application.
While it may not be the best way to show usage to external clients, it can be beneficial to show to other devs on your team if it is an internal API.
I think it's ok to put short code snippets into JavaDoc/XML comment type documentation but I think for really useful examples you'll have to bite the bullet and write an external document that you'll have to keep up to date. If it's an API you're documenting the API hopefully doesn't change so fast that maintenance becomes a burden.
We started writing API-usage documents after the first release of the API. That way you can be somewhat sure that it won't change so frequently. If it's for internal release the best documentation is probably just an example program with inline comments.