[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Doc strings of imenu--generic-function and imenu-generic-expression
From: |
Richard Stallman |
Subject: |
Re: Doc strings of imenu--generic-function and imenu-generic-expression incomplete |
Date: |
Mon, 17 Apr 2006 13:56:51 -0400 |
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.