* lisp/newcomment.el (comment-normalize-vars): Doc fix.

Fixes: debbugs:12583

2 files changed, 16 insertions, 5 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 3a196095597..bd40d0f0d30 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-10-23  Chong Yidong  <cyd@gnu.org>
+
+        * newcomment.el (comment-normalize-vars): Doc fix (Bug#12583).
+
 2012-10-23  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * subr.el (internal-temp-output-buffer-show): Rename from
diff --git a/lisp/newcomment.el b/lisp/newcomment.el
index a754c89c4ae..2ddfb2439af 100644
--- a/lisp/newcomment.el
+++ b/lisp/newcomment.el
@@ -24,7 +24,13 @@
 
 ;;; Commentary:
 
-;; A replacement for simple.el's comment-related functions.
+;; This library contains functions and variables for commenting and
+;; uncommenting source code.
+
+;; Prior to calling any `comment-*' function, you should ensure that
+;; `comment-normalize-vars' is first called to set up the appropriate
+;; variables; except for the `comment-*' commands, which call
+;; `comment-normalize-vars' automatically as a subroutine.
 
 ;;; Bugs:
 
@@ -326,10 +332,11 @@ terminated by the end of line (i.e. `comment-end' is empty)."
 
 ;;;###autoload
 (defun comment-normalize-vars (&optional noerror)
-  "Check and setup the variables needed by other commenting functions.
-Any command calling functions from newcomment.el should call this function
-before any other, so the rest of the code can assume that the variables are
-properly set."
+  "Check and set up variables needed by other commenting functions.
+All the `comment-*' commands call this function to set up various
+variables, like `comment-start', to ensure that the commenting
+functions work correctly.  Lisp callers of any other `comment-*'
+function should first call this function explicitly."
   (unless (and (not comment-start) noerror)
     (unless comment-start
       (let ((cs (read-string "No comment syntax is defined.  Use: ")))