`info`: support user-extensible documentation providers

[vemv]

Context

From time to time, there are DSLs that escape Clojure's normal var system.

For example:

(with-foo ;; some DSL-based macro
  BAR BAZ ;; symbols that aren't backed by a var (or local variable)
))

While we can't reasonably provide documentation for unqualified symbols that escape the var system, users / lib authors should be able to have that, unobstrusively.

There's the additional use case of unqualified keywords, as used by many popular libraries e.g. honeysql, Malli.

Proposed solution

Users should be able to have a dev/cider-doc.edn resource with content such as:

{[BAR BAZ] ;; all the symbols for which to apply certain rules
 {:info-provider com.corp/foo-info-provider
  :if            com.corp/foo-context?}

 [quux quuz]
 {:info-provider com.corp/alt-info-provider
  :if            com.corp/alt-context?}

 [:map :sequential :vector :maybe ,,,]
 {:info-provider malli/info-provider
  :if            malli/context?}}

 [:select :insert :join ,,,]
 {:info-provider honeysql/info-provider
  :if            honeysql/context?}}

Where:

• :info-provider is a function that returns an 'info' map, as Orchard does
• :if is a predicate that takes a Compliment context, returns whether the symbol is relevant for the current context
  • e.g. BAR may have different meanings depending on the context, as it's an unqualified symbol.
  • One is free to pass (constantly true) if one is confident enough in that the given symbols will be unique enough.
  • Besides from invoking the predicate with a Compliment context, we can bind *ns* and *file* in case that helps users.

These .edn files (and their backing functions) could be distributed as normal Maven artifacts, so that people can add them to their :dev alias.

Additional context

Our info middleware already takes a context as input.

https://github.com/clojure-emacs/cider-nrepl/blob/dd3a83a93b5cc406b539a903dde6e2b2889f50f1/src/cider/nrepl/middleware/info.clj#L81-L82

So it would seem easy and unobstrusive to observe cider-doc.edn files, handle them, and if they aren't found / do not apply, proceed with the normal code path.

Finally, it's OK to have multiple cider-doc.edn files in the classpath (just like with data_readers.clj - they're merged)

[vemv]

@bbatsov @alexander-yakushev feel free to review the idea :)

Seems a small task, would be happy to get it right from the start regardless.

[alexander-yakushev]

Sounds like a quite useful feature!

[vemv]

Thanks!

I reckon that an alternative approach would be to use defsource.

But we've had troudbles in the past getting people to correctly wire up defsource to our mranderson-ized Compliment.

It also can be considered compelling for lib authors to code just an .edn and one or two defns, without having them pull a dependency, interact with it, etc.

I would however foster defsource for authors wanting to offer custom completions for their libraries.

But I'd see first if the simplest thing (doc only, dep-free) does get acceptance.