Add ability to tune Compliment behavior with var's metadata

[alexander-yakushev]

This change introduces two Var metadata tags that Compliment honors:

• :completion/hide true. When a var has this meta flag, it will not be suggested by the completion like if it were private. This can be used for cases where you don't want to expose and encourage some "private API" to the user, but at the same time you cannot make it private because the other namespaces of your library to use it.
• :completion/locals :let|:defn|:letfn|:doseq. You can mark your own macro with this metadata to tell Compliment that your macro can be searched for locals in the same places as in the respective basic Clojure macro.

@vemv, @bbatsov Any thoughts? I have a few concerns:

• Is this useful?
• What prefix is better, :compliment/ or :completion/? The former is more consistent, but the latter is more generic and can potentially be used by other completion providers (e.g. cljs-tooling) without paying Compliment unnecessary credit.
• ^:completion/hide or ^:completion/hidden?

[vemv]

Thanks for pinging me!

Any thoughts?

I like this approach and would gladly add the meta in my projects that define let/defn/letfn (e.g.).

At the same time, I feel it doesn't have to be exclusive, relative to what I proposed in #76

My reasoning being:

• projects that use names let, letfn (instead of let+ or whatever) are good citizens in that they properly use clj's ns system and don't force odd names on the ecosystem
  • it can be nice to give those projects the affordance of automatically better tooling
• other projects may not be aware of what Compliment is (can happen even among CIDER users), or they might be reluctant to adding metadata for tooling they don't use (I've faced this situation when proposing :style/indent to be added)
• sometimes, code is in a semi-broken state (e.g. a tools.namespace (refresh) failed), so the metadata may be temporarily unavailable
  • Compliment could precisely help recover the state :)

So, personally I'd mix both approaches, favoring metadata over an heuristic (mine is, after all) if both are positive.

Is this useful?

Definitely, when I created #76 I hacked locally the described fix and it increased accuracy for my/let.

[bbatsov]

Is this useful?

Yeah, definitely.

What prefix is better, :compliment/ or :completion/? The former is more consistent, but the latter is more generic and can potentially be used by other completion providers (e.g. cljs-tooling) without paying Compliment unnecessary credit.

I prefer the more generic name, as it's something we can adopt directly in nREPL as well for its built-in completion logic.

^:completion/hide or ^:completion/hidden?

Hard question. I'd probably go with hidden for no particular reason, other that I don't like verbs as metadata.

[bbatsov]

So, personally I'd mix both approaches, favoring metadata over an heuristic (mine is, after all) if both are positive.

My experience with heuristics is a mixed bag, as you always end up with some false positives that someone will be complaining about (e.g. clojure-mode's decision to threat anything named defsomething as a definion created problems with the word default and so on). I'm not opposed to coming up with some heuristic, but for me the metadata route is much better as it's both simple and deterministic.

other projects may not be aware of what Compliment is (can happen even among CIDER users), or they might be reluctant to adding metadata for tooling they don't use (I've faced this situation when proposing :style/indent to be added)

It's a process. The longer something is out in the open and the better the tool support for it, the more popular it will be become. Now that so many editors internally use cider-nrepl I think the metadata concept became a bit more common, plus it validated the premise that neutral names like style are better. :D

[vemv]

LGTM, this will be a great addition to CIDER 🍻.