clojure-emacs / clojure-emacs/cider-nrepl

`info`: support user-extensible documentation providers

Open
#861 3 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.