* 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.

lisp/ChangeLog

 2012-05-08  Stefan Monnier  <monnier@iro.umontreal.ca>
 
+	* 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  <rgm@gnu.org>

lisp/imenu.el

-;;; 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 @@ The function in this variable is called when selecting a normal index-item.")
   (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 @@ Don't move point."
 (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 @@ There is one simple element with negative POSITION; selecting that
 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 @@ element recalculates the buffer's index alist.")
 ;;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-;;;
-;;; 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 @@ element recalculates the buffer's index alist.")
 	(/ (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 @@ element recalculates the buffer's index alist.")
 	 (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 @@ element recalculates the buffer's index alist.")
     (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 @@ See `imenu--index-alist' for the format of the index alist."
   ;; 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 @@ See `imenu--index-alist' for the format of the index alist."
       (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 @@ A trivial interface to `imenu-add-to-menubar' suitable for use in a hook."
 
 (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)