;;; 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>
;;; 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:
If there are any \\(...\\) pairs, the comment delimiter text is held to begin
at the place matched by the close of the first pair.")
;;;###autoload
-(put 'comment-start-skip 'safe-local-variable 'string-or-null-p)
+(put 'comment-start-skip 'safe-local-variable 'stringp)
;;;###autoload
(defvar comment-end-skip nil
"Regexp to match the end of a comment plus everything back to its body.")
;;;###autoload
-(put 'comment-end-skip 'safe-local-variable 'string-or-null-p)
+(put 'comment-end-skip 'safe-local-variable 'stringp)
;;;###autoload
(defvar comment-end (purecopy "")
"String to insert to end a new comment.
Should be an empty string if comments are terminated by end-of-line.")
;;;###autoload
-(put 'comment-end 'safe-local-variable 'string-or-null-p)
+(put 'comment-end 'safe-local-variable 'stringp)
;;;###autoload
(defvar comment-indent-function 'comment-indent-default
(lambda () (set (make-local-variable 'comment-inline-offset) 2)))
See `comment-padding' for whole-line comments."
- :version "24.2"
+ :version "24.3"
:type 'integer
:group 'comment)
;;;###autoload
(defun comment-normalize-vars (&optional noerror)
- "Check and setup the variables needed by other commenting functions.
-Functions autoloaded from newcomment.el, being entry points, 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: ")))