At least, it doesn't work when used from the company-mode backend.
The reason seems to be, eclim--completion-candidates returns the values by the key info from the completion list (for java-mode, at least), but eclim--completion-documentation compares them to the completion values. The former include the arguments list and the closing paren, the latter don't.
I think there are two problems here. The first is that we use different keys for java mode (info) and other modes (completion). When I wrote the documentation function I was testing it mainly with XML mode, and didn't consider the java version. I've fixed this in the latest commit.
The other problem is that (at least for me) eclim doesn't really return that much useful documentation for java mode. It's basically the same stuff that we already display in the completion menu.
In company-eclim (bundled backend), I solved that problem by showing less text in the candidates. :) I cut out owner class and return type and only them it for meta.
But displaying proper javadocs would be better, of course. Eclim docs say it has :JavaDocPreview in the Vim client. Is there perchance a file that lists all commands we can pass to Eclim daemon?
Ah, I see you already have eclim-java-show-documentation-for-current-element. Completion frameworks could use that (or some extracted function), auto-complete in document and company-mode in doc-buffer.
I think the biggest problem with that approach is that it requires the candidate to be already inserted into the buffer, and the buffer saved. Eclim doesn't seem to require that arguments are defined, have matching types, etc, it just looks at their number, so inserting the cancidate temporarily, saving, doing the lookup, then undo, should work.
I tried going another way, but java_docsearch is not useful (it returns a list of links to javadocs hosted at download.oracle.com).
Passing an URL parameter (-u) to java_element_doc sees a promising alternative, but the URL uses the internal Eclipse format: eclipse-javadoc:%E2%98%82=tsst/%5C/usr%5C/lib%5C/jvm%5C/java-7-openjdk-amd64%5C/jre%5C/lib%5C/rt.jar%3Cjava.lang(StringBuilder.class%E2%98%83StringBuilder~append~Ljava.lang.String;%E2%98%82StringBuilder.
I'm stopping here, but it should be possible to reconstruct this using the method signature and the path to the containing jar. The latter can be obtained with java_search:
$ ./eclim -command java_search -p "java.lang.StringBuilder"