[Docs] Tweak wording

Author: bbatsov

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)
 ----