[nongnu] elpa/cider c3e939f2d6 2/2: [Docs] Tweak wording

[ELPA Syncer]

branch: elpa/cider
commit c3e939f2d6321a6667d655b23008b1585f13f4d9
Author: Bozhidar Batsov <bozhidar@batsov.dev>
Commit: Bozhidar Batsov <bozhidar@batsov.dev>

    [Docs] Tweak wording
---
 doc/modules/ROOT/pages/usage/code_evaluation.adoc | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/modules/ROOT/pages/usage/code_evaluation.adoc 
b/doc/modules/ROOT/pages/usage/code_evaluation.adoc
index c5115d1ad0..be20bf0f57 100644
--- a/doc/modules/ROOT/pages/usage/code_evaluation.adoc
+++ b/doc/modules/ROOT/pages/usage/code_evaluation.adoc
@@ -302,9 +302,9 @@ 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
+=== Evaluating code 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`:
+By default, when using the defun-level eval commands inside a top-level 
`comment` form the return value is always `nil`. Calling 
`cider-eval-defun-up-to-point` with point at `<point>` also returns `nil`:
 
 [source,clojure]
 ----
@@ -316,7 +316,12 @@ By default, when using the defun-style eval commands 
inside a comment the return
   *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:
+That's not a bug, that's simply how the `comment` form works (it simply returns
+`nil` when evaluated).  However, it is often desirable to treat the form the
+point is in as if was not inside a comment. To help with this `clojure-mode`
+supplies the variable `clojure-toplevel-inside-comment-form`. If this variable
+is set to `t` then `defun`-level commands will ignore the `comment`
+wrapper. Let's revisit the previous example:
 
 [source,clojure]
 ----
@@ -336,7 +341,7 @@ With `cider-eval-defun-at-point` we get:
   (let [b "str"]
     (-> b
         keyword<point>
-        name));;=> "str"
+        name)) ;;=> "str"
   *e)
 ----