Documentation improvements

[bbatsov]

It'd be nice if the documentation function returned the complete javadoc for a class/member. That way we'll be able to create a documentation middleware that we'll behave similarly for Clojure vars and Java classes/members. It would also be good if we could reduce the ambiguity and return just a single documentation entry (that way the short documentation could used to implement eldoc-like functionality for Java stuff). That would require us to know the type of the receiver, but we'll know that most of the time (at least for already evaluated code).

[alexander-yakushev]

I thought about this the other day. The most portable way of doing such thing is compactly packaging Javadocs into a Clojure library (in this case, to cider-nrepl). Easier to do but JVM-only is reading javadocs from the harddrive.

Could you elaborate on the second part of your question? Especially about the type of the receiver. Currently Compliment figures out receiver type only for vars, and it seems this is the farthest we can get.

[bbatsov]

I assume you've added the documentation function just to be able to show the doc tooltips on completion, but for me it seems that using to show the javadoc about a class/member at point also seems like a reasonable that.

(.doSomething x)

I haven't looked at the current implementation, but it seems clear that without knowing the type of x one cannot be certain where doSomething is defined (if there are more than two classes that define a method with the same name and number of args). And in the case of completion:

(.doSomething  )

it seems that fetching the correct javadoc if next to impossible because at this point nothing is known about the receiver.

Not sure if I've managed to clarify what I meant.

As for the javadoc packaging - we cannot package the javadocs of all possible libraries a user might want to use, so it seems more sensible to try to access whatever he has locally. Or I'm missing something? (haven't really researched the topic)

[bbatsov]

Btw, documentation doesn't seem to work properly with classes:

(compliment.core/documentation "String" *ns*)
=> "\n  nil\n"

[alexander-yakushev]

1. There is only a limited number of cases when in (.domSomething x) we can figure out what x is and provide the completion for the intended type. Currently I just smash all fitting signatures together specifying which class they belong.
2. If Javadocs were to be read from disk, I would rather have CIDER providing this completion source. Otherwise non-local nREPL instances (like on Android for example) wouldn't have access to the docs. Yes, it would split the completion into two entities which is bad, but in any case something is to be sacrificed. Anyway, I can give it more thought.
3. Do you mean that it shouldn't return anything? That can be fixed, yes.

[bbatsov]

1 & 2 - Understood.
3 - not sure what the best return value would be. I guess it can be a list of fully qualified class names to be aligned with the result for methods.

[alexander-yakushev]

I guess it can be a list of fully qualified class names to be aligned with the result for methods.

Not sure I got you right on this one. Do you mean to show the fully qualified classname together with all method signatures of this class?

Also, since non-qualified classnames are taken from (ns-map), we could be aware about only one qualified class to match the requested unqualified name. Just sayin'.

[bbatsov]

Not sure I got you right on this one. Do you mean to show the fully qualified classname together with all method signatures of this class?

Yeah, that'd be great.

Also, since non-qualified classnames are taken from (ns-map), we could be aware about only one qualified class to match the requested unqualified name. Just sayin'.

That's fine I guess.

[alexander-yakushev]

OK, I fixed the docs for classnames, now it shows the list of members for the class. Popup doc now also shows the docstring for namespaces.

I will keep the issue open as reminder to implement javadoc, although I'm not so sure this will be ever done. I tried to search for projects that provide kinda-JavaIDE for Emacs, and couldn't find one that does javadoc parsing and displaying. Most just send the user to the browser.

[bbatsov]

We've implemented the Javadoc handling (using the JDK's built-in javadoc parser) in cider-nrepl. You might refer to the code there if it's something you'd like to add to compliment.

[alexander-yakushev]

Thanks for pointing that out. I like how it doesn't depend on any external files with documentation. Making a link for myself so I can find it later: jeffvalk/cider-nrepl@8b6d3d5

[alexander-yakushev]

I'd rather keep this open. I haven't touched javadocs integration into Compliment yet.

[behrica]

In this project there seems to be some code which can parse javadoc from a local maven repository:
https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/Docs.java

The method signature looks promising:

Optional memberDoc(String className, String memberName)