changeset 94291:171ae2941bb8

(speedbar-use-tool-tips-flag, speedbar-ignored-directory-regexp, speedbar-file-unshown-regexp, speedbar-file-regexp, speedbar-message, speedbar-item-info, speedbar-files-item-info, speedbar-maybe-add-localized-support, speedbar-insert-files-at-point, speedbar-dynamic-tags-function-list, speedbar-generic-list-positioned-group-p, speedbar-insert-generic-list, speedbar-fetch-replacement-function, speedbar-extract-one-symbol, speedbar-separator-face): Fix typos in docstrings. (speedbar-stealthy-function-list, speedbar-verbosity-level) (speedbar-supported-extension-expressions, speedbar-update-current-file) (speedbar-add-indicator, speedbar-tag-expand): Reflow docstring. (speedbar-use-imenu-flag, speedbar-ignored-directory-expressions) (speedbar-directory-unshown-regexp, speedbar-handle-delete-frame) (speedbar-show-info-under-mouse, speedbar-directory-buttons) (speedbar-check-vc-this-line, speedbar-files-line-directory) (speedbar-buffer-buttons, speedbar-buffer-buttons-temp) (speedbar-buffers-line-directory, speedbar-recenter-to-top) (speedbar-recenter): Doc fixes. (speedbar-update-speed, speedbar-navigating-speed): Add obsolescence declaration and remove redundant info in docstring.
author Juanma Barranquero <lekktu@gmail.com>
date Wed, 23 Apr 2008 04:46:10 +0000
parents 55b13d307a7a
children f07af351ed0b
files lisp/speedbar.el
diffstat 1 files changed, 55 insertions(+), 54 deletions(-) [+]
line wrap: on
line diff
--- a/lisp/speedbar.el	Wed Apr 23 04:07:11 2008 +0000
+++ b/lisp/speedbar.el	Wed Apr 23 04:46:10 2008 +0000
@@ -220,10 +220,10 @@
 where NAME is the name of the major display mode these functions are
 for, and the remaining elements FUNCTION are functions to call in order.
 Each function must return nil if interrupted, or t if completed.
-Stealthy functions which have a single operation should always return
-t.  Functions which take a long time should maintain a state (where
-they are in their speedbar related calculations) and permit
-interruption.  See `speedbar-check-vc' as a good example.")
+Stealthy functions which have a single operation should always return t.
+Functions which take a long time should maintain a state (where they
+are in their speedbar related calculations) and permit interruption.
+See `speedbar-check-vc' as a good example.")
 
 (defvar speedbar-mode-functions-list
   '(("files" (speedbar-item-info . speedbar-files-item-info)
@@ -325,11 +325,15 @@
 ;; When I moved to a repeating timer, I had the horrible missfortune
 ;; of loosing the ability for adaptive speed choice.  This update
 ;; speed currently causes long delays when it should have been turned off.
-(defvar speedbar-update-speed dframe-update-speed
-  "*Obsoleted variable.  Use `dframe-update-speed'.")
-
-(defvar speedbar-navigating-speed dframe-update-speed
-  "*Obsoleted variable.  Use `dframe-update-speed'.")
+(defvar speedbar-update-speed dframe-update-speed)
+(make-obsolete-variable 'speedbar-update-speed
+			'dframe-update-speed
+			"speedbar 1.0pre3")
+
+(defvar speedbar-navigating-speed dframe-update-speed)
+(make-obsolete-variable 'speedbar-navigating-speed
+			'dframe-update-speed
+			"speedbar 1.0pre3")
 ;;; END REMOVE THESE
 
 (defcustom speedbar-frame-parameters '((minibuffer . nil)
@@ -367,7 +371,7 @@
 			(sexp :tag "Value"))))
 
 (defcustom speedbar-use-imenu-flag (fboundp 'imenu)
-  "*Non-nil means use imenu for file parsing.  nil to use etags.
+  "*Non-nil means use imenu for file parsing, nil to use etags.
 XEmacs prior to 20.4 doesn't support imenu, therefore the default is to
 use etags instead.  Etags support is not as robust as imenu support."
   :tag "Use Imenu for tags"
@@ -378,7 +382,7 @@
   '((speedbar-fetch-dynamic-imenu . speedbar-insert-imenu-list)
     (speedbar-fetch-dynamic-etags . speedbar-insert-etags-list))
   "Set to a list of functions which will return and insert a list of tags.
-Each element is of the form ( FETCH .  INSERT ) where FETCH
+Each element is of the form ( FETCH . INSERT ) where FETCH
 is a function which takes one parameter (the file to tag) and returns a
 list of tags.  The tag list can be of any form as long as the
 corresponding insert method can handle it.  If it returns t, then an
@@ -387,7 +391,7 @@
 tags to insert.  It will then create the speedbar buttons.")
 
 (defcustom speedbar-use-tool-tips-flag (fboundp 'tooltip-mode)
-  "Non-nil means to use tool tips if they are avaialble.
+  "Non-nil means to use tool tips if they are available.
 When tooltips are not available, mouse-tracking and minibuffer
 display is used instead."
   :group 'speedbar
@@ -522,9 +526,10 @@
   :type 'hook)
 
 (defcustom speedbar-verbosity-level 1
-  "*Verbosity level of the speedbar.  0 means say nothing.
-1 means medium level verbosity.  2 and higher are higher levels of
-verbosity."
+  "*Verbosity level of the speedbar.
+0 means say nothing.
+1 means medium level verbosity.
+2 and higher are higher levels of verbosity."
   :group 'speedbar
   :type 'integer)
 
@@ -635,9 +640,9 @@
 	    "\\)$")))
 
 (defvar speedbar-ignored-directory-regexp nil
-  "Regular expression matching directorys speedbar will not switch to.
+  "Regular expression matching directories speedbar will not switch to.
 Created from `speedbar-ignored-directory-expressions' with the function
-`speedbar-extension-list-to-regex' (A misnamed function in this case.)
+`speedbar-extension-list-to-regex' (a misnamed function in this case.)
 Use the function `speedbar-add-ignored-directory-regexp', or customize the
 variable `speedbar-ignored-directory-expressions' to modify this variable.")
 
@@ -647,8 +652,8 @@
 (defcustom speedbar-ignored-directory-expressions
   '("[/\\]logs?[/\\]\\'")
   "*List of regular expressions matching directories speedbar will ignore.
-They should included directorys to directories which are notoriously very
-large and take a long time to load in.  Use the function
+They should included directories which are notoriously very large
+and take a long time to load in.  Use the function
 `speedbar-add-ignored-directory-regexp' to add new items to this list after
 speedbar is loaded.  You may place anything you like in this list
 before speedbar has been loaded."
@@ -662,8 +667,8 @@
 (defcustom speedbar-directory-unshown-regexp "^\\(\\..*\\)\\'"
   "*Regular expression matching directories not to show in speedbar.
 They should include commonly existing directories which are not
-useful.  It is no longer necessary to include include version-control
-directories here; see \\[vc-directory-exclusion-list\\]."
+useful.  It is no longer necessary to include version-control
+directories here; see `vc-directory-exclusion-list'."
   :group 'speedbar
   :type 'string)
 
@@ -676,12 +681,12 @@
     ;;               backup      refdir      lockfile
     (concat nstr "\\|#[^#]+#$\\|\\.\\.?\\'\\|\\.#"))
   "*Regexp matching files we don't want displayed in a speedbar buffer.
-It is generated from the variable `completion-ignored-extensions'")
+It is generated from the variable `completion-ignored-extensions'.")
 
 (defvar speedbar-file-regexp nil
   "Regular expression matching files we know how to expand.
 Created from `speedbar-supported-extension-expressions' with the
-function `speedbar-extension-list-to-regex'")
+function `speedbar-extension-list-to-regex'.")
 
 ;; this is dangerous to customize, because the defaults will probably
 ;; change in the future.
@@ -700,8 +705,7 @@
 singular expression.  This variable will be turned into
 `speedbar-file-regexp' for use with speedbar.  You should use the
 function `speedbar-add-supported-extension' to add a new extension at
-runtime, or use the configuration dialog to set it in your .emacs
-file.
+runtime, or use the configuration dialog to set it in your .emacs file.
 If you add an extension to this list, and it does not appear, you may
 need to also modify `completion-ignored-extension' which will also help
 file completion."
@@ -1054,7 +1058,7 @@
 
 (defun speedbar-handle-delete-frame (e)
   "Handle a delete frame event E.
-If the deleted frame is the frame SPEEDBAR is attached to,
+If the deleted frame is the frame speedbar is attached to,
 we need to delete speedbar also."
   (when (and speedbar-frame
 	     (eq (car (car (cdr e))) ;; frame to be deleted
@@ -1140,7 +1144,7 @@
   speedbar-buffer)
 
 (defmacro speedbar-message (fmt &rest args)
-  "Like message, but for use in the speedbar frame.
+  "Like `message', but for use in the speedbar frame.
 Argument FMT is the format string, and ARGS are the arguments for message."
   `(dframe-message ,fmt ,@args))
 
@@ -1292,8 +1296,7 @@
 	  (t (speedbar-message nil)))))))
 
 (defun speedbar-show-info-under-mouse ()
-  "Call the info function for the line under the mouse.
-Optional EVENT is currently not used."
+  "Call the info function for the line under the mouse."
   (let ((pos (mouse-position)))	; we ignore event until I use it later.
     (if (equal (car pos) speedbar-frame)
 	(save-excursion
@@ -1475,7 +1478,7 @@
 				  (point) (progn (end-of-line) (point))))))
 
 (defun speedbar-item-info ()
-  "Display info in the mini-buffer about the button the mouse is over.
+  "Display info in the minibuffer about the button the mouse is over.
 This function can be replaced in `speedbar-mode-functions-list' as
 `speedbar-item-info'."
   (interactive)
@@ -1553,7 +1556,7 @@
 	  nil)))))
 
 (defun speedbar-files-item-info ()
-  "Display info in the mini-buffer about the button the mouse is over."
+  "Display info in the minibuffer about the button the mouse is over."
   (if (not speedbar-shown-directories)
       (speedbar-generic-item-info)
     (or (speedbar-item-info-file-helper)
@@ -1830,7 +1833,7 @@
 	(speedbar-reconfigure-keymaps))))
 
 (defun speedbar-fetch-replacement-function (function)
-  "Return a current mode specific replacement for function, or nil.
+  "Return a current mode-specific replacement for function, or nil.
 Scans `speedbar-mode-functions-list' first for the current mode, then
 for FUNCTION."
   (cdr (assoc function
@@ -1847,7 +1850,7 @@
 ;;
 (defun speedbar-maybe-add-localized-support (buffer)
   "Quick check function called on BUFFERs by the speedbar timer function.
-Maintains the value of local variables which control speedbars use
+Maintains the value of local variables which control speedbar's use
 of the special mode functions."
   (or speedbar-special-mode-expansion-list
       (speedbar-add-localized-speedbar-support buffer)))
@@ -1933,7 +1936,7 @@
 
 (defun speedbar-directory-buttons (directory index)
   "Insert a single button group at point for DIRECTORY.
-Each directory directory part is a different button.  If part of the directory
+Each directory part is a different button.  If part of the directory
 matches the user directory ~, then it is replaced with a ~.
 INDEX is not used, but is required by the caller."
   (let* ((tilde (expand-file-name "~/"))
@@ -2082,7 +2085,7 @@
   "Insert list of FILES starting at point, and indenting all files to LEVEL.
 Tag expandable items with a +, otherwise a ?.  Don't highlight ? as we
 don't know how to manage them.  The input parameter FILES is a cons
-cell of the form ( 'DIRLIST .  'FILELIST )."
+cell of the form ( 'DIRLIST . 'FILELIST )."
   ;; Start inserting all the directories
   (let ((dirs (car files)))
     (while dirs
@@ -2150,7 +2153,7 @@
 	   )))
 
 (defun speedbar-generic-list-positioned-group-p (sublst)
-  "Non-nil of SUBLST is a group with a position."
+  "Non-nil if SUBLST is a group with a position."
   (and (stringp (car-safe sublst))
        (number-or-marker-p (car-safe (cdr-safe sublst)))
        (listp (cdr-safe (cdr-safe sublst)))
@@ -2407,7 +2410,7 @@
   "At LEVEL, insert a generic multi-level alist LST.
 Associations with lists get {+} tags (to expand into more nodes) and
 those with positions just get a > as the indicator.  {+} buttons will
-have the function EXPAND-FUN and the token is the CDR list.  The token
+have the function EXPAND-FUN and the token is the cdr list.  The token
 name will have the function FIND-FUN and not token."
   ;; Remove imenu rescan button
   (if (string= (car (car lst)) "*Rescan*")
@@ -2564,7 +2567,7 @@
 	    (setq expand-local t)
 
 	  ;; If this directory is NOT in the current list of available
-	  ;; directorys, then use the cache, and set the cache to our new
+	  ;; directories, then use the cache, and set the cache to our new
 	  ;; value.  Make sure to unhighlight the current file, or if we
 	  ;; come back to this directory, it might be a different file
 	  ;; and then we get a mess!
@@ -2770,8 +2773,7 @@
 (defun speedbar-update-current-file ()
   "Find the current file, and update our visuals to indicate its name.
 This is specific to file names.  If the file name doesn't show up, but
-it should be in the list, then the directory cache needs to be
-updated."
+it should be in the list, then the directory cache needs to be updated."
   (let* ((lastf (selected-frame))
 	 (newcfd (save-excursion
 		   (dframe-select-attached-frame speedbar-frame)
@@ -2840,8 +2842,8 @@
 
 (defun speedbar-add-indicator (indicator-string &optional replace-this)
   "Add INDICATOR-STRING to the end of this speedbar line.
-If INDICATOR-STRING is space, and REPLACE-THIS is a character, then
-the existing indicator is removed.  If there is already an
+If INDICATOR-STRING is space, and REPLACE-THIS is a character,
+then the existing indicator is removed.  If there is already an
 indicator, then do not add a space."
   (beginning-of-line)
   ;; The nature of the beast: Assume we are in "the right place"
@@ -2954,7 +2956,7 @@
       t)))
 
 (defun speedbar-check-vc-this-line (depth)
-  "Return t if the file on this line is check of of a version control system.
+  "Return t if the file on this line is checked out of a version control system.
 Parameter DEPTH is a string with the current depth of indentation of
 the file being checked."
   (let* ((d (string-to-number depth))
@@ -3198,7 +3200,7 @@
       (if rf (funcall rf depth) default-directory))))
 
 (defun speedbar-files-line-directory (&optional depth)
-  "Retrieve the directoryname associated with the current line.
+  "Retrieve the directory associated with the current line.
 This may require traversing backwards from DEPTH and combining the default
 directory with these items."
   (save-excursion
@@ -3483,9 +3485,8 @@
 
 (defun speedbar-tag-expand (text token indent)
   "Expand a tag sublist.  Imenu will return sub-lists of specialized tag types.
-Etags does not support this feature.  TEXT will be the button
-string.  TOKEN will be the list, and INDENT is the current indentation
-level."
+Etags does not support this feature.  TEXT will be the button string.
+TOKEN will be the list, and INDENT is the current indentation level."
   (cond ((string-match "+" text)	;we have to expand this file
 	 (speedbar-change-expand-button-char ?-)
 	 (speedbar-with-writable
@@ -3770,7 +3771,7 @@
 ;      (delete-region (match-beginning 1) (match-end 1)))))
 
 (defun speedbar-extract-one-symbol (expr)
-  "At point, return nil, or one alist in the form: (SYMBOL .  POSITION)
+  "At point, return nil, or one alist in the form (SYMBOL . POSITION).
 The line should contain output from etags.  Parse the output using the
 regular expression EXPR."
   (let* ((sym (if (stringp expr)
@@ -3867,12 +3868,12 @@
 
 (defun speedbar-buffer-buttons (directory zero)
   "Create speedbar buttons based on the buffers currently loaded.
-DIRECTORY is the directory to the currently active buffer, and ZERO is 0."
+DIRECTORY is the directory of the currently active buffer, and ZERO is 0."
   (speedbar-buffer-buttons-engine nil))
 
 (defun speedbar-buffer-buttons-temp (directory zero)
   "Create speedbar buttons based on the buffers currently loaded.
-DIRECTORY is the directory to the currently active buffer, and ZERO is 0."
+DIRECTORY is the directory of the currently active buffer, and ZERO is 0."
   (speedbar-buffer-buttons-engine t))
 
 (defun speedbar-buffer-buttons-engine (temp)
@@ -3950,7 +3951,7 @@
 			       (or (buffer-file-name buffer) "<No file>"))))))
 
 (defun speedbar-buffers-line-directory (&optional depth)
-  "Fetch the full directory to the file (buffer) specified on the current line.
+  "Fetch the directory of the file (buffer) specified on the current line.
 Optional argument DEPTH specifies the current depth of the back search."
   (save-excursion
     (end-of-line)
@@ -4037,11 +4038,11 @@
   (remove-hook 'pre-command-hook 'speedbar-unhighlight-one-tag-line))
 
 (defun speedbar-recenter-to-top ()
-  "Recenter the current buffer so POINT is on the top of the window."
+  "Recenter the current buffer so point is on the top of the window."
   (recenter 1))
 
 (defun speedbar-recenter ()
-  "Recenter the current buffer so POINT is in the center of the window."
+  "Recenter the current buffer so point is in the center of the window."
   (recenter (/ (window-height (selected-window)) 2)))
 
 
@@ -4114,7 +4115,7 @@
 				    (:background "white"
 				     :foreground "black"
 				     :overline "black")))
-  "Face used for separator labes in a display."
+  "Face used for separator labels in a display."
   :group 'speedbar-faces)
 
 ;; some edebug hooks