-
Notifications
You must be signed in to change notification settings - Fork 175
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
info
: support user-extensible documentation providers
#861
Comments
@bbatsov @alexander-yakushev feel free to review the idea :) Seems a small task, would be happy to get it right from the start regardless. |
info
: support user-extensible documentation providers
Sounds like a quite useful feature! |
Thanks! I reckon that an alternative approach would be to use 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 But I'd see first if the simplest thing (doc only, dep-free) does get acceptance. |
Context
From time to time, there are DSLs that escape Clojure's normal var system.
For example:
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: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 contextBAR
may have different meanings depending on the context, as it's an unqualified symbol.(constantly true)
if one is confident enough in that the given symbols will be unique enough.*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 acontext
as input.cider-nrepl/src/cider/nrepl/middleware/info.clj
Lines 81 to 82 in dd3a83a
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)
The text was updated successfully, but these errors were encountered: