Add ClojureDocs Command for examples to Rich Comments and to Output window

[PEZ]

What has Changed?

Reach Clojuredocs examples quickly.

Adding:

• ClojureDocs examples in the hover-lookup of symbols. So that you can at a glance see neat ways and caveats about Clojure core-ish symbols. Each example have two buttons/links:
  • To Rich Comment, prints the example to a rich comment below the top level form you are editing/viewing
  • To Output Window, prints the example to the REPL/Output window
• A command for printing all clojuredocs examples for the symbol under the cusror to a Rich Comment, default bound to ctrl+alt+r d (to go well with the command for opening a new rich comment block).
• A command for printing all clojuredocs examples for the symbol under the cursor to the Output/REPL window, ctrl+alt+o d

Here's a demo of the RFC one:

clojuredocs-sfc-surf.mp4

Also showing examples in hovers, with button at each example to print it as a rich comment. (Print to REPL window TBD.)

clojuredocs-hover-rfc.mp4

Please also consider retweeting:

• https://twitter.com/pappapez/status/1452325865933746185
• https://twitter.com/pappapez/status/1452409528511762444

There are some quirks with this:

• Currently this only works with Clojure REPLs, because I am using cider-nrepl to get the examples. I'm working on getting clojure-lsp to be able to serve these as well, and expect no ”Clojure only” issues there. See Add a clojuredocs command clojure-lsp/clojure-lsp#598 and Clojuredocs raw clojure-lsp/clojure-lsp#612
• When the examples contains unbalanced brackets, this introduces unbalance into the file. Not sure if we can live with that or need to somehow balance up the code (and not sure how to do that either 😄).

Fixes #689

My Calva PR Checklist

I have:

• Read How to Contribute.
• Directed this pull request at the dev branch. (Or have specific reasons to target some other branch.)
• Made sure I have changed the PR base branch, so that it is not published. (Sorry for the nagging.)
• Updated the [Unreleased] entry in CHANGELOG.md, linking the issue(s) that the PR is addressing.
• Figured if anything about the fix warrants tests on Mac/Linux/Windows/Remote/Whatever, and either tested it there if so, or mentioned it in the PR.
• Added to or updated docs in this branch, if appropriate
• Tested the VSIX built from the PR (so, after you've submitted the PR). You'll find the artifacts by clicking Show all checks in the CI section of the PR page, and then Details on the ci/circleci: build test. NB: You need to sign in/up at Circle CI to find the Artifacts tab.
  • Tested the particular change
  • Figured if the change might have some side effects and tested those as well.
  • Smoke tested the extension as such.
• Referenced the issue I am fixing/addressing in a commit message for the pull request.
  • If I am fixing the issue, I have used GitHub's fixes/closes syntax
  • If I am fixing just part of the issue, I have just referenced it w/o any of the "fixes” keywords.
• Created the issue I am fixing/addressing, if it was not present.

Ping @PEZ, @bpringe

[bpringe]

When the examples contains unbalanced brackets, this introduces unbalance into the file. Not sure if we can live with that or need to somehow balance up the code

I think we should not worry about that for a first version of this, or maybe ever, but we can see how it goes. This is great work!

[bpringe]

How does this > operator work when checking against a string?

[bpringe]

It seems that even if this check worked as it looks it was intended, there's a chance that null would be returned from this function just because the version was not a desired/capable version, and then the message here would be misleading, because clojureDocs would be null but symbol maybe would exist. It would say Only Clojure core (ish) symbols supported when really the version was not a desired/capable version.

I may have missed something, though.

[PEZ]

It's ”dictionary” order, character by character. https://javascript.info/comparison#string-comparison This type of check works because clojure-lsp has the kind of version string that it has. For other schemes, like Calva's, we would rather bring in a semver library, I think.

As for the message: good catch! I originally wrote that for when there were only direct commands fetching clojuredocs. Now when it happens on hover, it makes no sense to show a message. And we don't actually, so probably the message field should be removed. Which actually puts the whole NoDocsEntry construct into question (that might have been a bad idea all the time, I don't know 😄).

[bpringe]

Ah, thanks for educating me on that comparison!