From: Glenn Morris Date: Wed, 12 Jun 2013 07:54:57 +0000 (-0700) Subject: * lisp/ido.el: Convert some function comments to basic doc strings X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~2016^2~145^2~4 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=84d6f46535554f9f51aae3314313112e8d755c65;p=emacs.git * lisp/ido.el: Convert some function comments to basic doc strings --- diff --git a/lisp/ido.el b/lisp/ido.el index 14d1be5b763..47c05b080f7 100644 --- a/lisp/ido.el +++ b/lisp/ido.el @@ -3301,7 +3301,7 @@ for first matching file." res)) (defun ido-flatten-merged-list (items) - ;; Create a list of directory names based on a merged directory list. + "Create a list of directory names based on a merged directory list." (let (res) (while items (let* ((item (car items)) @@ -3404,7 +3404,7 @@ for first matching file." res)) (defun ido-make-buffer-list-1 (&optional frame visible) - ;; Return list of non-ignored buffer names + "Return list of non-ignored buffer names." (delq nil (mapcar (lambda (x) @@ -3414,12 +3414,12 @@ for first matching file." (buffer-list frame)))) (defun ido-make-buffer-list (default) - ;; Return the current list of buffers. - ;; Currently visible buffers are put at the end of the list. - ;; The hook `ido-make-buffer-list-hook' is run after the list has been - ;; created to allow the user to further modify the order of the buffer names - ;; in this list. If DEFAULT is non-nil, and corresponds to an existing buffer, - ;; it is put to the start of the list. + "Return the current list of buffers. +Currently visible buffers are put at the end of the list. +The hook `ido-make-buffer-list-hook' is run after the list has been +created to allow the user to further modify the order of the buffer names +in this list. If DEFAULT is non-nil, and corresponds to an existing buffer, +it is put to the start of the list." (let* ((ido-current-buffers (ido-get-buffers-in-frames 'current)) (ido-temp-list (ido-make-buffer-list-1 (selected-frame) ido-current-buffers))) (if ido-temp-list @@ -3461,9 +3461,9 @@ This is to make them appear as if they were \"virtual buffers\"." (nreverse (mapcar #'car ido-virtual-buffers)))))) (defun ido-make-choice-list (default) - ;; Return the current list of choices. - ;; If DEFAULT is non-nil, and corresponds to an element of choices, - ;; it is put to the start of the list. + "Return the current list of choices. +If DEFAULT is non-nil, and corresponds to an element of choices, +it is put to the start of the list." (let ((ido-temp-list ido-choice-list)) (if default (progn @@ -3475,7 +3475,7 @@ This is to make them appear as if they were \"virtual buffers\"." ido-temp-list)) (defun ido-to-end (items) - ;; Move the elements from ITEMS to the end of `ido-temp-list' + "Move the elements from ITEMS to the end of `ido-temp-list'." (mapc (lambda (elem) (setq ido-temp-list (delq elem ido-temp-list))) @@ -3519,8 +3519,8 @@ This is to make them appear as if they were \"virtual buffers\"." (file-name-all-completions "" dir)))) (defun ido-file-name-all-completions (dir) - ;; Return name of all files in DIR - ;; Uses and updates ido-dir-file-cache + "Return name of all files in DIR. +Uses and updates `ido-dir-file-cache'." (cond ((ido-is-unc-root dir) (mapcar @@ -3569,7 +3569,7 @@ This is to make them appear as if they were \"virtual buffers\"." (ido-file-name-all-completions-1 dir)))) (defun ido-remove-cached-dir (dir) - ;; Remove dir from ido-dir-file-cache + "Remove DIR from `ido-dir-file-cache'." (if (and ido-dir-file-cache (stringp dir) (> (length dir) 0)) (let ((cached (assoc dir ido-dir-file-cache))) @@ -3578,8 +3578,8 @@ This is to make them appear as if they were \"virtual buffers\"." (defun ido-make-file-list-1 (dir &optional merged) - ;; Return list of non-ignored files in DIR - ;; If MERGED is non-nil, each file is cons'ed with DIR + "Return list of non-ignored files in DIR +If MERGED is non-nil, each file is cons'ed with DIR." (and (or (ido-is-tramp-root dir) (ido-is-unc-root dir) (file-directory-p dir)) (delq nil @@ -3590,11 +3590,11 @@ This is to make them appear as if they were \"virtual buffers\"." (ido-file-name-all-completions dir))))) (defun ido-make-file-list (default) - ;; Return the current list of files. - ;; Currently visible files are put at the end of the list. - ;; The hook `ido-make-file-list-hook' is run after the list has been - ;; created to allow the user to further modify the order of the file names - ;; in this list. + "Return the current list of files. +Currently visible files are put at the end of the list. +The hook `ido-make-file-list-hook' is run after the list has been +created to allow the user to further modify the order of the file names +in this list." (let ((ido-temp-list (ido-make-file-list-1 ido-current-directory))) (setq ido-temp-list (sort ido-temp-list (if ido-file-extensions-order @@ -3635,8 +3635,8 @@ This is to make them appear as if they were \"virtual buffers\"." ido-temp-list)) (defun ido-make-dir-list-1 (dir &optional merged) - ;; Return list of non-ignored subdirs in DIR - ;; If MERGED is non-nil, each subdir is cons'ed with DIR + "Return list of non-ignored subdirs in DIR. +If MERGED is non-nil, each subdir is cons'ed with DIR." (and (or (ido-is-tramp-root dir) (file-directory-p dir)) (delq nil (mapcar @@ -3646,10 +3646,10 @@ This is to make them appear as if they were \"virtual buffers\"." (ido-file-name-all-completions dir))))) (defun ido-make-dir-list (default) - ;; Return the current list of directories. - ;; The hook `ido-make-dir-list-hook' is run after the list has been - ;; created to allow the user to further modify the order of the - ;; directory names in this list. + "Return the current list of directories. +The hook `ido-make-dir-list-hook' is run after the list has been +created to allow the user to further modify the order of the +directory names in this list." (let ((ido-temp-list (ido-make-dir-list-1 ido-current-directory))) (setq ido-temp-list (sort ido-temp-list #'ido-file-lessp)) (ido-to-end ;; move . files to end @@ -3680,10 +3680,9 @@ This is to make them appear as if they were \"virtual buffers\"." (defvar ido-bufs-in-frame) (defun ido-get-buffers-in-frames (&optional current) - ;; Return the list of buffers that are visible in the current frame. - ;; If optional argument `current' is given, restrict searching to the - ;; current frame, rather than all frames, regardless of value of - ;; `ido-all-frames'. + "Return the list of buffers that are visible in the current frame. +If optional argument CURRENT is given, restrict searching to the current +frame, rather than all frames, regardless of value of `ido-all-frames'." (let ((ido-bufs-in-frame nil)) (walk-windows 'ido-get-bufname nil (if current @@ -3692,7 +3691,7 @@ This is to make them appear as if they were \"virtual buffers\"." ido-bufs-in-frame)) (defun ido-get-bufname (win) - ;; Used by `ido-get-buffers-in-frames' to walk through all windows + "Used by `ido-get-buffers-in-frames' to walk through all windows." (let ((buf (buffer-name (window-buffer win)))) (unless (or (member buf ido-bufs-in-frame) (member buf ido-ignore-item-temp-list)) @@ -3705,7 +3704,7 @@ This is to make them appear as if they were \"virtual buffers\"." ;;; FIND MATCHING ITEMS (defun ido-set-matches-1 (items &optional do-full) - ;; Return list of matches in items + "Return list of matches in ITEMS." (let* ((case-fold-search ido-case-fold) (slash (and (not ido-enable-prefix) (ido-final-slash ido-text))) (text (if slash (substring ido-text 0 -1) ido-text)) @@ -3793,13 +3792,13 @@ This is to make them appear as if they were \"virtual buffers\"." (defun ido-set-matches () - ;; Set `ido-matches' to the list of items matching prompt + "Set `ido-matches' to the list of items matching prompt." (when ido-rescan (setq ido-matches (ido-set-matches-1 (reverse ido-cur-list) (not ido-rotate)) ido-rotate nil))) (defun ido-ignore-item-p (name re-list &optional ignore-ext) - ;; Return t if the buffer or file NAME should be ignored. + "Return t if the buffer or file NAME should be ignored." (or (member name ido-ignore-item-temp-list) (and ido-process-ignore-lists re-list @@ -3839,7 +3838,7 @@ This is to make them appear as if they were \"virtual buffers\"." (defvar ido-change-word-sub) (defun ido-find-common-substring (items subs) - ;; Return common string following SUBS in each element of ITEMS. + "Return common string following SUBS in each element of ITEMS." (let (res alist ido-change-word-sub) @@ -3859,8 +3858,8 @@ This is to make them appear as if they were \"virtual buffers\"." comp)))) (defun ido-word-matching-substring (word) - ;; Return part of WORD before 1st match to `ido-change-word-sub'. - ;; If `ido-change-word-sub' cannot be found in WORD, return nil. + "Return part of WORD before first match to `ido-change-word-sub'. +If `ido-change-word-sub' cannot be found in WORD, return nil." (let ((case-fold-search ido-case-fold)) (let ((m (string-match ido-change-word-sub (ido-name word)))) (if m @@ -3869,7 +3868,7 @@ This is to make them appear as if they were \"virtual buffers\"." nil)))) (defun ido-makealist (res) - ;; Return dotted pair (RES . 1). + "Return dotted pair (RES . 1)." (cons res 1)) (defun ido-choose-completion-string (choice &rest ignored) @@ -4052,8 +4051,8 @@ Record command in `command-history' if optional RECORD is non-nil." (defun ido-buffer-window-other-frame (buffer) - ;; Return window pointer if BUFFER is visible in another frame. - ;; If BUFFER is visible in the current frame, return nil. + "Return window pointer if BUFFER is visible in another frame. +If BUFFER is visible in the current frame, return nil." (let ((blist (ido-get-buffers-in-frames 'current))) ;;If the buffer is visible in current frame, return nil (if (member buffer blist) @@ -4537,9 +4536,8 @@ For details of keybindings, see `ido-find-file'." )))) (defun ido-completions (name) - ;; Return the string that is displayed after the user's text. - ;; Modified from `icomplete-completions'. - + "Return the string that is displayed after the user's text. +Modified from `icomplete-completions'." (let* ((comps ido-matches) (ind (and (consp (car comps)) (> (length (cdr (car comps))) 1) ido-merged-indicator))