clojure-emacs / clojure-emacs/cider-nrepl
`info`: support user-extensible documentation providers
- Dominant language
- Clojure
- Stars
- 749
- Forks
- 182
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 6
Description
## Context
From time to time, there are DSLs that escape Clojure's normal var system.
For example:
```clj
(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:
```clj
{[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)
Contributor guide
Assessment
This issue has not been assessed yet.