;;; 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:
;;;###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: ")))
Moves point to inside the comment and returns the position of the
comment-starter. If no comment is found, moves point to LIMIT
and raises an error or returns nil if NOERROR is non-nil."
- ;; FIXME: If a comment-start appears inside a comment, we may erroneously
- ;; stop there. This can be rather bad in general, but since
- ;; comment-search-backward is only used to find the comment-column (in
- ;; comment-set-column) and to find the comment-start string (via
- ;; comment-beginning) in indent-new-comment-line, it should be harmless.
- (if (not (re-search-backward comment-start-skip limit t))
- (unless noerror (error "No comment"))
- (beginning-of-line)
- (let* ((end (match-end 0))
- (cs (comment-search-forward end t))
- (pt (point)))
- (if (not cs)
- (progn (beginning-of-line)
- (comment-search-backward limit noerror))
- (while (progn (goto-char cs)
- (comment-forward)
- (and (< (point) end)
- (setq cs (comment-search-forward end t))))
- (setq pt (point)))
- (goto-char pt)
- cs))))
+ (let (found end)
+ (while (and (not found)
+ (re-search-backward comment-start-skip limit t))
+ (setq end (match-end 0))
+ (unless (and comment-use-syntax
+ (nth 8 (syntax-ppss (or (match-end 1)
+ (match-beginning 0)))))
+ (setq found t)))
+ (if (not found)
+ (unless noerror (error "No comment"))
+ (beginning-of-line)
+ (let ((cs (comment-search-forward end t))
+ (pt (point)))
+ (if (not cs)
+ (progn (beginning-of-line)
+ (comment-search-backward limit noerror))
+ (while (progn (goto-char cs)
+ (comment-forward)
+ (and (< (point) end)
+ (setq cs (comment-search-forward end t))))
+ (setq pt (point)))
+ (goto-char pt)
+ cs)))))
(defun comment-beginning ()
"Find the beginning of the enclosing comment.
(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))