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.

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)