[Emacs-diffs] /srv/bzr/emacs/trunk r110623: * lisp/newcomment.el (comment-normalize-vars): Doc fix.

[Chong Yidong]

------------------------------------------------------------
revno: 110623
fixes bug: http://debbugs.gnu.org/12583
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2012-10-23 10:17:36 +0800
message:
  * lisp/newcomment.el (comment-normalize-vars): Doc fix.
modified:
  lisp/ChangeLog
  lisp/newcomment.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-10-23 01:18:47 +0000
+++ b/lisp/ChangeLog    2012-10-23 02:17:36 +0000
@@ -1,3 +1,7 @@
+2012-10-23  Chong Yidong  <address@hidden>
+
+       * newcomment.el (comment-normalize-vars): Doc fix (Bug#12583).
+
 2012-10-23  Stefan Monnier  <address@hidden>
 
        * subr.el (internal-temp-output-buffer-show): Rename from

=== modified file 'lisp/newcomment.el'
--- a/lisp/newcomment.el        2012-10-09 16:37:51 +0000
+++ b/lisp/newcomment.el        2012-10-23 02:17:36 +0000
@@ -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 @@
 
 ;;;###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: ")))