branch: elpa/cider
commit 2d3b18377a9927fd0e70d77263576bc7e11a5904
Author: Bozhidar Batsov <bozhi...@batsov.dev>
Commit: Bozhidar Batsov <bozhi...@batsov.dev>
[Docs] Document the connection hooks
---
doc/modules/ROOT/pages/config/basic_config.adoc | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/doc/modules/ROOT/pages/config/basic_config.adoc
b/doc/modules/ROOT/pages/config/basic_config.adoc
index d3f8c2de21..cedb71795f 100644
--- a/doc/modules/ROOT/pages/config/basic_config.adoc
+++ b/doc/modules/ROOT/pages/config/basic_config.adoc
@@ -265,3 +265,24 @@ wrapping instead of line truncating.
IMPORTANT: This variable should be set *before* loading CIDER (which means
before
`require`-ing it or autoloading it).
+
+== nREPL Connection Hooks
+
+CIDER provides the hooks `cider-connected-hook` and `cider-disconnected-hook`
+that get triggered when an nREPL connection is established or closed
respectively.
+
+Here's how CIDER uses the first hook internally to display its famous
inspirational
+messages on connect:
+
+[source,lisp]
+----
+(defun cider--maybe-inspire-on-connect ()
+ "Display an inspiration connection message."
+ (when cider-connection-message-fn
+ (message "Connected! %s" (funcall cider-connection-message-fn))))
+
+(add-hook 'cider-connected-hook #'cider--maybe-inspire-on-connect)
+----
+
+NOTE: There are also lower-level `nrepl-connected-hook` and
`nrepl-disconnected-hook` that CIDER uses internally. Most of the time
end-users would be better off using
+the CIDER-level hooks instead.
