We would also like any feedback you have on what exactly would be helpful in terms of examples, etc. You can send that feedback here: devinfo@splunk.com
We plan to publish a complete Java SDK Reference as the SDK matures (it is currently in Preview and has not reached Beta yet). That content is not available today outside of the source code (as Damien pointed out). I will update this answer with a link when those docs are posted.
UPDATE April 6, 2012: The Java SDK Reference is now available at http://docs.splunk.com/Documentation/JavaSDK. We will update and refresh this content as we continue to work on the SDK.
Well, additionally , I find reading the source code to be quite useful.It is well written and commented, ergo, self documenting.
The ant build script(build.xml) also has a "javadoc" target for generating html javadocs.
I already know that these are the 2 docs. Is there any more?? Is it that all the docs are found at these 2 locations?