Calva: Include material from clojuredocs.org in function documentation

[crispinb]

The clojuredocs.org documentation for clojure core is really handy. The examples are invaluable given how terse clojure docs can be.

It would be great to have access to the clojuredocs for a given function - whether added to the 'show hover' doc output used in the current implementation, or via a new command.

[bpringe]

I think this is a good idea.

[PEZ]

Love it! I think the Orchard has support for it.

[zackteo]

I wonder if the current pop up documentation will work well with this tho. In CIDER another window will open up, this works well because some of the functions in clojuredocs.org have a lot of examples

(I use CIDER but a friend of mine is getting into Clojure through Calva)

[crispinb]

It might be a bit unwieldy with the current popup, true enough. Hard to tell for sure without seeing it, but the tradeoff might be worth it for those of us who make use of clojuredocs.

[bpringe]

Couple of ideas here:

1) We use a webview to show the clojuredocs page for the particular function. Here the webview would just be used to show html, and nothing more, so it would not give us trouble like the old repl window.

2) However, we could also use an editor like the new repl window, so all the examples from clojuredocs would be immediately executable from the editor. (Have not thought this through further yet - might be more trouble than it's worth - are executable examples really necessary/helpful? The output is usually shown with the examples anyway.)

[PEZ]

I like number 2.

We don't need to populate the pop-up with this. We could have commands that paste it to the output/repl.

[zackteo]

Sorry maybe I'm mistaken but don't both 1 and 2 work out? That is I'm assuming both options it will open in another window :o ? I agree with @PEZ about not populating the pop-up.

I don't think the examples need to be immediately executable. Just need to be able to seamlessly check the docs, close it and continue with what you are working on. That's my thoughts

[bpringe]

1 and 2 are just different approaches to the same thing, but both would open another window, yes. I find this arguably the same as just using a browser window though, if it has to be another window in the editor.

I do worry though that if we were to use the output window that could interrupt a person's workflow. Someone might be working on some code in the repl window, and if they run the command to look something up in that window their code will be interrupted by the clojuredocs output.

[PEZ]

We can paste it into an untitled editor window with the extension repl-file. It would make it easy to do whatever you like with the information and examples, including evaluate them.

[glebovmaksim]

It's good enough for me to just show the output in a webview. If I want to evaluate example I can just copy it to a regular repl window (and as @bpringe said, the examples usually have the output in the comments already). I'm afraid that the repl-file solution will bring a lot of questions (if it is a regular repl-file, in which namespace will the evaluation work? can we close the non-empty untitled file without confirmation dialog? etc). But maybe I just misunderstood the idea.

[PEZ]

I think you are understanding it. But you might not be as reluctant as I am to bring in webviews. 😄 And you might not be as keen as I am on experimenting with example code. That is the first thing I do when I try to understand things.

[bpringe]

I mostly agree with @glebovmaksim here in terms of the added complexity / questions a repl-file would bring, but if we start using "fiddle files" in the future as you've mentioned @PEZ, we might have a better solution/workflow around those.

I do think though that using a webview purely as read-only is significantly less troublesome than what was done before with the old repl window, and makes sense here (ignoring being able to edit/run the examples), similar to a markdown preview webview.

Editing/evaluating the examples in-place sounds fun/cool, but again, questions. The results would be printed at the bottom of all the examples, not the particular example you evaluated, making it hard to work with the examples, which then leads to copying/pasting anyway if wanting to play with the examples.

I think in most cases of someone looking at clojuredocs, they do not try to run the examples, but use them merely as a quick "aha" and move on with their code.

Lastly, a quick incremental solution would be to add a command or link in the hover/description that opens a browser to the clojuredocs page. I honestly find flipping between a browser window and vscode about the same amount of effort/trouble as if the clojuredocs page were opened in another window in vscode.

Basically, if we aren't putting the clojuredocs material in a hover, I find it almost pointless not to just use a browser outside of vs code.

[crispinb]

I think in most cases of someone looking at clojuredocs, they do not try to run the examples, but use them merely as a quick "aha" and move on with their code.

I think this is half right, but it's the right half! As a current clojure learner, I might well spend some time perusing clojuredocs for a group of functions, perhaps copying bits out to a scratch project to play with etc. But the web site is fine for that. It's a quite different activity from a quick lookup in an editing session - there what the user wants is to briefly (a) glance at and then (b) dismiss the info. Although VS Code might not provide the perfect infrastructure for that (yet?), the hover is the closest approximation IMO.

Personally (and others' workflows differ of course) opening up a separate OS window (browser) or editor frame (whether web view or standard editor) offers just a bit more friction than this kind of quick lookup demands.

a quick incremental solution would be to add a command or link in the hover/description that opens a browser to the clojuredocs page.

Yep, this is how IntelliJ does it (a modal popup, with a further command to launch an external browser window or other document viewer).

In an ideal world that command/link would be configurable - eg. to launch a browser or Zeal/Dash (or similar) if installed, but that may be a bridge too far at this stage.

In summary, I think the logical distinction between "look up while editing" and "single-minded reading of documentation" is worth maintaining.

[glebovmaksim]

Good point, @crispinb!

Yep, this is how IntelliJ does it (a modal popup, with a further command to launch an external browser window or other document viewer).

It seems like it has more than that. I wonder if this can be implemented in a similar way in VSCode...

[PEZ]

I think we can do that. How is this dialog brought up in Cursive?

[glebovmaksim]

It appears on hover. The same way as function signature / docstring in Calva.

[crispinb]

.. or via keyboard shortcut (ctrl-Q on linux). And once it's up there's another keyboard shortcut (F4) to jump to the documented source code. Some IntelliJ language plugins (but not Cursive IIRC) offer a further shortcut to launch external documentation (eg. a web page, or open a documentation browsing app like Dash or Zeal).

[bpringe]

So it looks like we came back to adding these to the hover? :smile: I really don't see an issue with that.