Merged from emacs@sv.gnu.org

Patches applied:

 * emacs@sv.gnu.org/emacs--devo--0--patch-413
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-414
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-415
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-416
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-417
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-418
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-419
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-420
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-421
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-422
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-423
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-424
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-425
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-426
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-427
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-428
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-429
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-430
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-431
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-432
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-433
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-434
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-435
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-436
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-437
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-438
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-439
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-440
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-441
   lisp/url/url-methods.el: Fix format error when http_proxy is empty string

 * emacs@sv.gnu.org/emacs--devo--0--patch-442
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-443
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-444
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-445
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-446
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-447
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-448
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-449
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-450
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-451
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-452
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-453
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-454
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-455
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-456
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-457
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-458
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-459
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-460
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-461
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-462
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-463
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-464
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-465
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-466
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-467
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-468
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-469
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-470
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-471
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-472
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-473
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-128
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-129
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-130
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-131
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-132
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-133
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-134
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-135
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-136
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-137
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-138
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-139
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-140
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-141
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-142
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-143
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-144
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-145
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-146
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-147
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-148
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-149
   Update from CVS


git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-582

1 files changed, 25 insertions, 9 deletions

diff --git a/lisp/emacs-lisp/timer.el b/lisp/emacs-lisp/timer.el
index 82eac50c874..0c66a207351 100644
--- a/lisp/emacs-lisp/timer.el
+++ b/lisp/emacs-lisp/timer.el
@@ -32,9 +32,11 @@
 ;; Layout of a timer vector:
 ;; [triggered-p high-seconds low-seconds usecs repeat-delay
 ;;  function args idle-delay]
+;; triggered-p is nil if the timer is active (waiting to be triggered),
+;;  t if it is inactive ("already triggered", in theory)
 
 (defun timer-create ()
-  "Create a timer object."
+  "Create a timer object which can be passed to `timer-activate'."
   (let ((timer (make-vector 8 nil)))
     (aset timer 0 t)
     timer))
@@ -173,6 +175,10 @@ fire repeatedly that many seconds apart."
 (defun timer-activate (timer &optional triggered-p reuse-cell)
   "Put TIMER on the list of active timers.
 
+If TRIGGERED-P is t, that means to make the timer inactive
+\(put it on the list, but mark it as already triggered).
+To remove from the list, use `cancel-timer'.
+
 REUSE-CELL, if non-nil, is a cons cell to reuse instead
 of allocating a new one."
   (if (and (timerp timer)
@@ -256,10 +262,10 @@ of allocating a new one."
   (setq timer-idle-list (delq timer timer-idle-list))
   nil)
 
-;; Remove TIMER from the list of active timers or idle timers.
-;; Only to be used in this file.  It returns the cons cell
-;; that was removed from the list.
 (defun cancel-timer-internal (timer)
+  "Remove TIMER from the list of active timers or idle timers.
+Only to be used in this file.  It returns the cons cell
+that was removed from the timer list."
   (let ((cell1 (memq timer timer-list))
 	(cell2 (memq timer timer-idle-list)))
     (if cell1
@@ -270,7 +276,9 @@ of allocating a new one."
 
 ;;;###autoload
 (defun cancel-function-timers (function)
-  "Cancel all timers scheduled by `run-at-time' which would run FUNCTION."
+  "Cancel all timers which would run FUNCTION.
+This affects ordinary timers such as are scheduled by `run-at-time',
+and idle timers such as are scheduled by `run-with-idle-timer'."
   (interactive "aCancel timers of function: ")
   (let ((tail timer-list))
     (while tail
@@ -284,12 +292,19 @@ of allocating a new one."
       (setq tail (cdr tail)))))
 
 ;; Record the last few events, for debugging.
-(defvar timer-event-last-2 nil)
-(defvar timer-event-last-1 nil)
-(defvar timer-event-last nil)
+(defvar timer-event-last nil
+  "Last timer that was run.")
+(defvar timer-event-last-1 nil
+  "Next-to-last timer that was run.")
+(defvar timer-event-last-2 nil
+  "Third-to-last timer that was run.")
 
 (defvar timer-max-repeats 10
-  "*Maximum number of times to repeat a timer, if real time jumps.")
+  "*Maximum number of times to repeat a timer, if many repeats are delayed.
+Timer invocations can be delayed because Emacs is suspended or busy,
+or because the system's time changes.  If such an occurrence makes it
+appear that many invocations are overdue, this variable controls
+how many will really happen.")
 
 (defun timer-until (timer time)
   "Calculate number of seconds from when TIMER will run, until TIME.
@@ -440,6 +455,7 @@ This function returns a timer object which you can use in `cancel-timer'."
     timer))
 
 (defun with-timeout-handler (tag)
+  "This is the timer function used for the timer made by `with-timeout'."
   (throw tag 'timeout))
 
 ;;;###autoload (put 'with-timeout 'lisp-indent-function 1)