diff --git a/cider-docstring.el b/cider-docstring.el
index 965ead993..dda6c3184 100644
--- a/cider-docstring.el
+++ b/cider-docstring.el
@@ -148,10 +148,13 @@ Prioritize rendering as much as possible while staying within `cider-docstring-m
     (concat string (when (> (length lines) max-lines) "..."))))
 
 (defun cider-docstring--format (string)
-  "Return a nicely formatted STRING to be displayed to the user."
-  ;; As this is a literal docstring from the source code and
-  ;; there are two spaces at the beginning of lines in docstrings,
-  ;; we remove them to make it align nicely when it is displayed.
+  "Return a nicely formatted STRING to be displayed to the user.
+
+We need to format the docstring before displaying it to the user because
+it is obtained from the source code.  For example, this means that it has
+two spaces before each line used for indentation.  While displaying the
+docstring to the user, we usually want to control indentation and other
+aspects of the presentation, so we need to format it beforehand."
   (replace-regexp-in-string "\n  " "\n" string))
 
 (provide 'cider-docstring)