Re: Doc strings of imenu--generic-function and imenu-generic-expression incomplete

[Richard Stallman]

Does this clear it up?

*** imenu.el    07 Feb 2006 18:16:12 -0500      1.115
--- imenu.el    17 Apr 2006 10:10:28 -0400      
***************
*** 208,225 ****
  
  ;;;###autoload
  (defvar imenu-create-index-function 'imenu-default-create-index-function
!   "The function to use for creating a buffer index.
  
! It should be a function that takes no arguments and returns an index
! of the current buffer as an alist.
  
! Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
! Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
! A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
! The function `imenu--subalist-p' tests an element and returns t
! if it is a sub-alist.
! 
! This function is called within a `save-excursion'.")
  ;;;###autoload
  (make-variable-buffer-local 'imenu-create-index-function)
  
--- 208,220 ----
  
  ;;;###autoload
  (defvar imenu-create-index-function 'imenu-default-create-index-function
!   "The function to use for creating an index alist of the current buffer.
  
! It should be a function that takes no arguments and returns
! an index alist of the current buffer.  The function is
! called within a `save-excursion'.
  
! See `imenu--index-alist' for the format of the buffer index alist.")
  ;;;###autoload
  (make-variable-buffer-local 'imenu-create-index-function)
  
***************
*** 431,445 ****
  ;; The latest buffer index.
  ;; Buffer local.
  (defvar imenu--index-alist nil
!   "The buffer index computed for this buffer in Imenu.
! Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
! Special elements look like (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...).
! A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).")
  
  (make-variable-buffer-local 'imenu--index-alist)
  
  (defvar imenu--last-menubar-index-alist nil
!   "The latest buffer index used to update the menu bar menu.")
  
  (make-variable-buffer-local 'imenu--last-menubar-index-alist)
  
--- 426,452 ----
  ;; The latest buffer index.
  ;; Buffer local.
  (defvar imenu--index-alist nil
!   "The buffer index alist computed for this buffer in Imenu.
! 
! Simple elements in the alist look like (INDEX-NAME . POSITION).
! POSITION is the buffer position of the item; to go to the item
! is simply to move point to that position.
! 
! Special elements look like (INDEX-NAME POSITION FUNCTION ARGUMENTS...).
! To \"go to\" a special element means applying FUNCTION
! to INDEX-NAME, POSITION, and the ARGUMENTS.
! 
! A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
! The function `imenu--subalist-p' tests an element and returns t
! if it is a sub-alist.
! 
! There is one simple element with negative POSITION; selecting that
! element recalculates the buffer's index alist."
  
  (make-variable-buffer-local 'imenu--index-alist)
  
  (defvar 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)
  
***************
*** 547,565 ****
  
  
  (defun imenu--make-index-alist (&optional noerror)
!   "Create an index-alist for the definitions in the current buffer.
! 
  Report an error if the list is empty unless NOERROR is supplied and
  non-nil.
  
! Simple elements in the alist look like (INDEX-NAME . INDEX-POSITION).
! Special elements look like (INDEX-NAME FUNCTION ARGUMENTS...).
! A nested sub-alist element looks like (INDEX-NAME SUB-ALIST).
! The function `imenu--subalist-p' tests an element and returns t
! if it is a sub-alist.
! 
! There is one simple element with negative POSITION; that's intended
! as a way for the user to ask to recalculate the buffer's index alist."
    (or (and imenu--index-alist
           (or (not imenu-auto-rescan)
               (and imenu-auto-rescan
--- 554,565 ----
  
  
  (defun imenu--make-index-alist (&optional noerror)
!   "Create an index alist for the definitions in the current buffer.
! This works by using the hook function `imenu-create-index-function'.
  Report an error if the list is empty unless NOERROR is supplied and
  non-nil.
  
! See `imenu--index-alist' for the format of the index alist."
    (or (and imenu--index-alist
           (or (not imenu-auto-rescan)
               (and imenu-auto-rescan
***************
*** 657,667 ****
  (make-variable-buffer-local 'imenu-syntax-alist)
  
  (defun imenu-default-create-index-function ()
!   "*Wrapper for index searching functions.
  
! Moves point to end of buffer and then repeatedly calls
  `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
! Their results are gathered into an index alist."
    ;; These should really be done by setting imenu-create-index-function
    ;; in these major modes.  But save that change for later.
    (cond ((and imenu-prev-index-position-function
--- 657,671 ----
  (make-variable-buffer-local 'imenu-syntax-alist)
  
  (defun imenu-default-create-index-function ()
!   "*Default function to create an index alist of the current buffer.
  
! The most general method is to move point to end of buffer, then repeatedly 
call
  `imenu-prev-index-position-function' and `imenu-extract-index-name-function'.
! All the results returned by the latter are gathered into an index alist.
! This method is used if those two variables are non-nil.
! 
! The alternate method, which is the one most often used, is to call
! `imenu--generic-function' with `imenu-generic-expression' as argument."
    ;; These should really be done by setting imenu-create-index-function
    ;; in these major modes.  But save that change for later.
    (cond ((and imenu-prev-index-position-function
***************
*** 687,713 ****
        (t
         (error "This buffer cannot use 
`imenu-default-create-index-function'"))))
  
- ;; Not used and would require cl at run time
- ;; (defun imenu--flatten-index-alist (index-alist &optional concat-names 
prefix)
- ;;   ;; Takes a nested INDEX-ALIST and returns a flat index alist.
- ;;   ;; If optional CONCAT-NAMES is non-nil, then a nested index has its
- ;;   ;; name and a space concatenated to the names of the children.
- ;;   ;; Third argument PREFIX is for internal use only.
- ;;   (mapcan
- ;;    (lambda (item)
- ;;      (let* ((name (car item))
- ;;        (pos (cdr item))
- ;;        (new-prefix (and concat-names
- ;;                         (if prefix
- ;;                             (concat prefix imenu-level-separator name)
- ;;                           name))))
- ;;        (cond
- ;;    ((or (markerp pos) (numberp pos))
- ;;     (list (cons new-prefix pos)))
- ;;    (t
- ;;     (imenu--flatten-index-alist pos new-prefix)))))
- ;;    index-alist))
- 
  ;;;
  ;;; Generic index gathering function.
  ;;;
--- 691,696 ----
***************
*** 724,730 ****
  ;; This function can be called with quitting disabled,
  ;; so it needs to be careful never to loop!
  (defun imenu--generic-function (patterns)
!   "Return an index of the current buffer as an alist.
  
  PATTERNS is an alist with elements that look like this:
   (MENU-TITLE REGEXP INDEX)
--- 707,713 ----
  ;; This function can be called with quitting disabled,
  ;; so it needs to be careful never to loop!
  (defun imenu--generic-function (patterns)
!   "Return an index alist of the current buffer based on PATTERNS.
  
  PATTERNS is an alist with elements that look like this:
   (MENU-TITLE REGEXP INDEX)
***************
*** 733,740 ****
  with zero or more ARGUMENTS.  The former format creates a simple
  element in the index alist when it matches; the latter creates a
  special element of the form (NAME POSITION-MARKER FUNCTION
! ARGUMENTS...)  with FUNCTION and ARGUMENTS copied from
! `imenu-generic-expression'.
  
  MENU-TITLE is a string used as the title for the submenu or nil
  if the entries are not nested.
--- 716,722 ----
  with zero or more ARGUMENTS.  The former format creates a simple
  element in the index alist when it matches; the latter creates a
  special element of the form (NAME POSITION-MARKER FUNCTION
! ARGUMENTS...) with FUNCTION and ARGUMENTS copied from PATTERNS.
  
  MENU-TITLE is a string used as the title for the submenu or nil
  if the entries are not nested.