Merge from emacs-24; up to 2012-12-21T07:35:02Z!ueno@gnu.org

[gnu-emacs] / lisp / newcomment.el

diff --git a/lisp/newcomment.el b/lisp/newcomment.el
index a754c89c4ae81b3d928a4046addfedd99f7c2c5c..bcb5f721ae81706da0d7f13980b7da47f9b14e57 100644 (file)
--- a/lisp/newcomment.el
+++ b/lisp/newcomment.el
@@ -1,6 +1,6 @@
 ;;; newcomment.el --- (un)comment regions of buffers -*- lexical-binding: t -*-
 
-;; Copyright (C) 1999-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1999-2013 Free Software Foundation, Inc.
 
 ;; Author: code extracted from Emacs-20's simple.el
 ;; Maintainer: Stefan Monnier <monnier@iro.umontreal.ca>
@@ -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: ")))
@@ -1199,7 +1206,8 @@ changed with `comment-style'."
 (defun comment-box (beg end &optional arg)
   "Comment out the BEG .. END region, putting it inside a box.
 The numeric prefix ARG specifies how many characters to add to begin- and
-end- comment markers additionally to what `comment-add' already specifies."
+end- comment markers additionally to what variable `comment-add' already
+specifies."
   (interactive "*r\np")
   (comment-normalize-vars)
   (let ((comment-style (if (cadr (assoc comment-style comment-styles))