Api docs do tend to merely provide method signatures, which is great when you know what you are doing, but when you come upon a bunch of generics, implicit parameters, and thats in the docs for the first time, you end up combing through a lot of stuff. In many cases, a simple example use case embedded in the document with console output of the use case would admittedly be very helpful.