cider-nrepl
cider-nrepl copied to clipboard
`info`: support user-extensible documentation providers
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.
- e.g.
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)