I just had to read through incomprehensible API docs. It's painful. Why isn't there a standard for API docs, just like there is a standard for language-specific library docs (e.g. rubydoc)?
There's no standard for RESTful API docs because a RESTful API, per se, doesn't need docs. If an API is really RESTful, the content types used in it need documentation which describes both the content structure and the meaningful operations against it, and with those the API is self-describing.<p>Of course, most "RESTful" APIs are variations on RPC over HTTP, not actually RESTful.