[Emacs-diffs] trunk r112944: * lisp/ido.el: Convert some function comments to basic doc strings

[Glenn Morris]

------------------------------------------------------------
revno: 112944
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2013-06-12 00:54:57 -0700
message:
  * lisp/ido.el: Convert some function comments to basic doc strings
modified:
  lisp/ido.el                    ido.el-20091113204419-o5vbwnq5f7feedwu-2430

=== modified file 'lisp/ido.el'
--- a/lisp/ido.el       2013-06-12 07:46:01 +0000
+++ b/lisp/ido.el       2013-06-12 07:54:57 +0000
@@ -3301,7 +3301,7 @@
     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 @@
     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 @@
         (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 @@
                 (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 @@
     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 @@
     (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 @@
     (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 @@
 
 
 (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 @@
              (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 @@
     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 @@
              (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 @@
 (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 @@
     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 @@
 ;;; 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 @@
 
 
 (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 @@
 (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 @@
        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 @@
         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 @@
 
 
 (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 @@
        ))))
 
 (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))