[Emacs-diffs] /srv/bzr/emacs/emacs-24 r108161: * lisp/imenu.el: Misc cleanup. Make docstrings out of comments.

[Stefan Monnier]

------------------------------------------------------------
revno: 108161
committer: Stefan Monnier <address@hidden>
branch nick: trunk
timestamp: Tue 2012-05-08 10:19:08 -0400
message:
  * lisp/imenu.el: Misc cleanup.  Make docstrings out of comments.
  Use lexical-binding.
  (imenu--index-alist, imenu--last-menubar-index-alist)
  (imenu-menubar-modified-tick): Use defvar-local.
  (imenu--split-menu): Remove unused var.
  (imenu--cleanup-seen): Declare as global.
  (imenu--cleanup): Use dolist.
modified:
  lisp/ChangeLog
  lisp/imenu.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-05-08 14:11:47 +0000
+++ b/lisp/ChangeLog    2012-05-08 14:19:08 +0000
@@ -1,5 +1,13 @@
 2012-05-08  Stefan Monnier  <address@hidden>
 
+       * imenu.el: Misc cleanup.  Make docstrings out of comments.
+       Use lexical-binding.
+       (imenu--index-alist, imenu--last-menubar-index-alist)
+       (imenu-menubar-modified-tick): Use defvar-local.
+       (imenu--split-menu): Remove unused var.
+       (imenu--cleanup-seen): Declare as global.
+       (imenu--cleanup): Use dolist.
+
        * subr.el (defvar-local): Add debug spec and doc-string position.
 
 2012-05-08  Glenn Morris  <address@hidden>

=== modified file 'lisp/imenu.el'
--- a/lisp/imenu.el     2012-05-04 23:16:47 +0000
+++ b/lisp/imenu.el     2012-05-08 14:19:08 +0000
@@ -1,4 +1,4 @@
-;;; imenu.el --- framework for mode-specific buffer indexes
+;;; imenu.el --- framework for mode-specific buffer indexes  -*- 
lexical-binding: t -*-
 
 ;; Copyright (C) 1994-1998, 2001-2012 Free Software Foundation, Inc.
 
@@ -266,12 +266,12 @@
   (and (consp (cdr item)) (listp (cadr item))
        (not (eq (car (cadr item)) 'lambda))))
 
-;; Macro to display a progress message.
-;; RELPOS is the relative position to display.
-;; If RELPOS is nil, then the relative position in the buffer
-;; is calculated.
-;; PREVPOS is the variable in which we store the last position displayed.
-(defmacro imenu-progress-message (prevpos &optional relpos reverse)
+(defmacro imenu-progress-message (_prevpos &optional _relpos _reverse)
+  "Macro to display a progress message.
+RELPOS is the relative position to display.
+If RELPOS is nil, then the relative position in the buffer
+is calculated.
+PREVPOS is the variable in which we store the last position displayed."
 
 ;; Made obsolete/empty, as computers are now faster than the eye, and
 ;; it had problems updating the messages correctly, and could shadow
@@ -419,8 +419,7 @@
 (defconst imenu--rescan-item '("*Rescan*" . -99))
 
 ;; The latest buffer index.
-;; Buffer local.
-(defvar imenu--index-alist nil
+(defvar-local imenu--index-alist nil
   "The buffer index alist computed for this buffer in Imenu.
 
 Simple elements in the alist look like (INDEX-NAME . POSITION).
@@ -439,16 +438,12 @@
 element recalculates the buffer's index alist.")
 ;;;###autoload(put 'imenu--index-alist 'risky-local-variable t)
 
-(make-variable-buffer-local 'imenu--index-alist)
-
-(defvar imenu--last-menubar-index-alist nil
+(defvar-local imenu--last-menubar-index-alist nil
   "The latest buffer index alist used to update the menu bar menu.")
 
-(make-variable-buffer-local 'imenu--last-menubar-index-alist)
-
-;; History list for 'jump-to-function-in-buffer'.
-;; Making this buffer local caused it not to work!
-(defvar imenu--history-list nil)
+(defvar imenu--history-list nil
+  ;; Making this buffer local caused it not to work!
+  "History list for 'jump-to-function-in-buffer'.")
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;
@@ -456,21 +451,18 @@
 ;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-;;;
-;;; Sort function
-;;; Sorts the items depending on their index name.
-;;; An item looks like (NAME . POSITION).
-;;;
 (defun imenu--sort-by-name (item1 item2)
+  "Comparison function to sort items depending on their index name.
+An item looks like (NAME . POSITION)."
   (string-lessp (car item1) (car item2)))
 
 (defun imenu--sort-by-position (item1 item2)
   (< (cdr item1) (cdr item2)))
 
 (defun imenu--relative-position (&optional reverse)
-  ;; Support function to calculate relative position in buffer
-  ;; Beginning of buffer is 0 and end of buffer is 100
-  ;; If REVERSE is non-nil then the beginning is 100 and the end is 0.
+  "Support function to calculate relative position in buffer.
+Beginning of buffer is 0 and end of buffer is 100
+If REVERSE is non-nil then the beginning is 100 and the end is 0."
   (let ((pos (point))
        (total (buffer-size)))
     (and reverse (setq pos (- total pos)))
@@ -479,11 +471,10 @@
        (/ (1- pos) (max (/ total 100) 1))
       (/ (* 100 (1- pos)) (max total 1)))))
 
-;; Split LIST into sublists of max length N.
-;; Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
-;;
-;; The returned list DOES NOT share structure with LIST.
 (defun imenu--split (list n)
+  "Split LIST into sublists of max length N.
+Example (imenu--split '(1 2 3 4 5 6 7 8) 3)-> '((1 2 3) (4 5 6) (7 8))
+The returned list DOES NOT share structure with LIST."
   (let ((remain list)
        (result '())
        (sublist '())
@@ -502,20 +493,18 @@
         (push (nreverse sublist) result))
     (nreverse result)))
 
-;;; Split the alist MENULIST into a nested alist, if it is long enough.
-;;; In any case, add TITLE to the front of the alist.
-;;; If IMENU--RESCAN-ITEM is present in MENULIST, it is moved to the
-;;; beginning of the returned alist.
-;;;
-;;; The returned alist DOES NOT share structure with MENULIST.
 (defun imenu--split-menu (menulist title)
+  "Split the alist MENULIST into a nested alist, if it is long enough.
+In any case, add TITLE to the front of the alist.
+If IMENU--RESCAN-ITEM is present in MENULIST, it is moved to the
+beginning of the returned alist.
+The returned alist DOES NOT share structure with MENULIST."
   (let ((menulist (copy-sequence menulist))
-        keep-at-top tail)
+        keep-at-top)
     (if (memq imenu--rescan-item menulist)
        (setq keep-at-top (list imenu--rescan-item)
              menulist (delq imenu--rescan-item menulist)))
-    (setq tail menulist)
-    (dolist (item tail)
+    (dolist (item menulist)
       (when (imenu--subalist-p item)
        (push item keep-at-top)
        (setq menulist (delq item menulist))))
@@ -530,32 +519,28 @@
     (cons title
          (nconc (nreverse keep-at-top) menulist))))
 
-;;; Split up each long alist that are nested within ALIST
-;;; into nested alists.
-;;;
-;;; Return a split and sorted copy of ALIST. The returned alist DOES
-;;; NOT share structure with ALIST.
 (defun imenu--split-submenus (alist)
-  (mapcar (function
-          (lambda (elt)
-            (if (and (consp elt)
-                     (stringp (car elt))
-                     (listp (cdr elt)))
-                (imenu--split-menu (cdr elt) (car elt))
-              elt)))
+  "Split up each long alist that are nested within ALIST into nested alists.
+Return a split and sorted copy of ALIST.  The returned alist DOES
+NOT share structure with ALIST."
+  (mapcar (lambda (elt)
+            (if (and (consp elt)
+                     (stringp (car elt))
+                     (listp (cdr elt)))
+                (imenu--split-menu (cdr elt) (car elt))
+              elt))
          alist))
 
-;;; Truncate all strings in MENULIST to imenu-max-item-length
 (defun imenu--truncate-items (menulist)
-  (mapcar (function
-          (lambda (item)
-            (cond
-             ((consp (cdr item))
-              (imenu--truncate-items (cdr item)))
-             ;; truncate if necessary
-             ((and (numberp imenu-max-item-length)
-                   (> (length (car item)) imenu-max-item-length))
-              (setcar item (substring (car item) 0 imenu-max-item-length))))))
+  "Truncate all strings in MENULIST to `imenu-max-item-length'."
+  (mapcar (lambda (item)
+            (cond
+             ((consp (cdr item))
+              (imenu--truncate-items (cdr item)))
+             ;; truncate if necessary
+             ((and (numberp imenu-max-item-length)
+                   (> (length (car item)) imenu-max-item-length))
+              (setcar item (substring (car item) 0 imenu-max-item-length)))))
          menulist))
 
 
@@ -585,13 +570,12 @@
   ;; Add a rescan option to the index.
   (cons imenu--rescan-item imenu--index-alist))
 
-;;; Find all markers in alist and makes
-;;; them point nowhere.
-;;; The top-level call uses nil as the argument;
-;;; non-nil arguments are in recursive calls.
-(defvar imenu--cleanup-seen)
+(defvar imenu--cleanup-seen nil)
 
 (defun imenu--cleanup (&optional alist)
+  "Find all markers in ALIST and make them point nowhere.
+If ALIST is nil (the normal case), use `imenu--index-alist'.
+Non-nil arguments are in recursive calls."
   ;; If alist is provided use that list.
   ;; If not, empty the table of lists already seen
   ;; and use imenu--index-alist.
@@ -599,18 +583,14 @@
       (setq imenu--cleanup-seen (cons alist imenu--cleanup-seen))
     (setq alist imenu--index-alist imenu--cleanup-seen (list alist)))
 
-  (and alist
-       (mapc
-       (lambda (item)
-         (cond
-          ((markerp (cdr item))
-           (set-marker (cdr item) nil))
-          ;; Don't process one alist twice.
-          ((memq (cdr item) imenu--cleanup-seen))
-          ((imenu--subalist-p item)
-           (imenu--cleanup (cdr item)))))
-       alist)
-       t))
+  (when alist
+    (dolist (item alist)
+      (cond
+       ((markerp (cdr item)) (set-marker (cdr item) nil))
+       ;; Don't process one alist twice.
+       ((memq (cdr item) imenu--cleanup-seen))
+       ((imenu--subalist-p item) (imenu--cleanup (cdr item)))))
+    t))
 
 (defun imenu--create-keymap (title alist &optional cmd)
   (list* 'keymap title
@@ -981,10 +961,9 @@
 
 (defvar imenu-buffer-menubar nil)
 
-(defvar imenu-menubar-modified-tick 0
+(defvar-local imenu-menubar-modified-tick 0
   "The value of (buffer-chars-modified-tick) as of the last call
 to `imenu-update-menubar'.")
-(make-variable-buffer-local 'imenu-menubar-modified-tick)
 
 (defun imenu-update-menubar ()
   (when (and (current-local-map)