[nongnu] elpa/cider 81482982fb 1/2: Add docs for evaluating in comments

[ELPA Syncer]

branch: elpa/cider
commit 81482982fbade63f83d780151d8acec54743a218
Author: lycheese <dev@lycheese.org>
Commit: Bozhidar Batsov <bozhidar@batsov.dev>

    Add docs for evaluating in comments
    
    Document clojure-toplevel-inside-comment-form for changing the
    behaviour of defun-style commands.
---
 doc/modules/ROOT/pages/usage/code_evaluation.adoc | 38 +++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/modules/ROOT/pages/usage/code_evaluation.adoc 
b/doc/modules/ROOT/pages/usage/code_evaluation.adoc
index 07bebc83d9..c5115d1ad0 100644
--- a/doc/modules/ROOT/pages/usage/code_evaluation.adoc
+++ b/doc/modules/ROOT/pages/usage/code_evaluation.adoc
@@ -302,6 +302,44 @@ You can also use the command 
`cider-kill-last-result`(kbd:[C-c C-v k]) after any
 eval command to store its result in the kill ring. This works even when the
 `cider-eval-register` feature is disabled.
 
+=== Evaluating inside comments
+
+By default, when using the defun-style eval commands inside a comment the 
return value is always `nil`. Calling `cider-eval-defun-up-to-point` with point 
at `<point>` also returns `nil`:
+
+[source,clojure]
+----
+(comment
+  (let [b "str"]
+    (-> b
+        keyword<point> ;;=> nil
+        name))
+  *e)
+----
+
+However, as it is often desirable to treat the form the point is in as if was 
not inside a comment, `clojure-mode` supplies the variable 
`clojure-toplevel-inside-comment-form`. If this variable is set to `t` then 
instead of `nil` we get:
+
+[source,clojure]
+----
+(comment
+  (let [b "str"]
+    (-> b
+        keyword<point> ;;=> :str
+        name))
+  *e)
+----
+
+With `cider-eval-defun-at-point` we get:
+
+[source,clojure]
+----
+(comment
+  (let [b "str"]
+    (-> b
+        keyword<point>
+        name));;=> "str"
+  *e)
+----
+
 
 == Keybindings