branch: master
commit 203bfb1f95b43f0448ee6225e58930ccb333547f
Author: fabacino <[email protected]>
Commit: Oleh Krehel <[email protected]>
ivy.el: Fix checkdoc warnings
Fixes #1064
---
ivy.el | 116 ++++++++++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 76 insertions(+), 40 deletions(-)
diff --git a/ivy.el b/ivy.el
index 00a5499..6755478 100644
--- a/ivy.el
+++ b/ivy.el
@@ -158,7 +158,7 @@ The fancy display style highlights matching parts of the
regexp,
a behavior similar to `swiper'.
This setting depends on `add-face-text-property' - a C function
-available as of Emacs 24.5. Fancy style will render poorly in
+available as of Emacs 24.5. Fancy style will render poorly in
earlier versions of Emacs."
:type '(choice
(const :tag "Plain" nil)
@@ -171,14 +171,14 @@ Usually a quick exit out of the minibuffer."
(defcustom ivy-extra-directories '("../" "./")
"Add this to the front of the list when completing file names.
-Only \"./\" and \"../\" apply here. They appear in reverse order."
+Only \"./\" and \"../\" apply here. They appear in reverse order."
:type '(repeat :tag "Dirs"
(choice
(const :tag "Parent Directory" "../")
(const :tag "Current Directory" "./"))))
(defcustom ivy-use-virtual-buffers nil
- "When non-nil, add `recentf-mode' and bookmarks to `ivy-switch-buffer'."
+ "When non-nil, add recent files and bookmarks to `ivy-switch-buffer'."
:type 'boolean)
(defcustom ivy-display-function nil
@@ -1035,6 +1035,8 @@ Example use:
)")
(defun ivy-recursive-restore ()
+ "Restore the above state when exiting the minibuffer.
+See variable `ivy-recursive-restore' for further information."
(when (and ivy-recursive-last
ivy-recursive-restore
(not (eq ivy-last ivy-recursive-last)))
@@ -1337,8 +1339,8 @@ functions that have candidates in the natural buffer
order, like
`org-refile' or `Man-goto-section'.
A list can be used to associate multiple sorting functions with a
-collection. The car of the list is the current sort
-function. This list can be rotated with `ivy-rotate-sort'.
+collection. The car of the list is the current sort
+function. This list can be rotated with `ivy-rotate-sort'.
The entry associated with t is used for all fall-through cases.
@@ -1357,7 +1359,7 @@ See also `ivy-sort-max-size'."
:group 'ivy)
(defun ivy--sort-function (collection)
- "Retrieve sort function from `ivy-sort-functions-alist'"
+ "Retrieve sort function for COLLECTION from `ivy-sort-functions-alist'."
(cdr (assoc collection ivy-sort-functions-alist)))
(defun ivy-rotate-sort ()
@@ -1469,7 +1471,7 @@ contains a single candidate.")
PROMPT is a format string, normally ending in a colon and a
space; %d anywhere in the string is replaced by the current
-number of matching candidates. For the literal % character,
+number of matching candidates. For the literal % character,
escape it with %%. See also `ivy-count-format'.
COLLECTION is either a list of strings, a function, an alist, or
@@ -1498,7 +1500,7 @@ UPDATE-FN is called each time the current candidate(s) is
changed.
When SORT is t, use `ivy-sort-functions-alist' for sorting.
-ACTION is a lambda function to call after selecting a result. It
+ACTION is a lambda function to call after selecting a result. It
takes a single string argument.
UNWIND is a lambda function to call before exiting.
@@ -1799,6 +1801,7 @@ This is useful for recursive `ivy-read'."
(setf (ivy-state-initial-input ivy-last) initial-input)))
(defun ivy-add-prompt-count (prompt)
+ "Add count information to PROMPT."
(cond ((string-match "%.*d" prompt)
prompt)
((null ivy-count-format)
@@ -1934,7 +1937,10 @@ The previous string is between `ivy-completion-beg' and
`ivy-completion-end'."
0)))
(defun ivy-completion-in-region (start end collection &optional predicate)
- "An Ivy function suitable for `completion-in-region-function'."
+ "An Ivy function suitable for `completion-in-region-function'.
+The function completes the text between START and END using COLLECTION.
+PREDICATE (a function called with no arguments) says when to exit.
+See `completion-in-region' for further information."
(let* ((enable-recursive-minibuffers t)
(str (buffer-substring-no-properties start end))
(completion-ignore-case case-fold-search)
@@ -2017,7 +2023,7 @@ Minibuffer bindings:
;;* Implementation
;;** Regex
(defun ivy-re-match (re-seq str)
- "Return non-nil if RE-SEQ matches STR.
+ "Return non-nil if RE-SEQ is matched by STR.
RE-SEQ is a list of (RE . MATCH-P).
@@ -2121,8 +2127,10 @@ When GREEDY is non-nil, join words in a greedy way."
(defun ivy--regex-ignore-order--part (str &optional discard)
"Re-build regex from STR by splitting at spaces.
-Ignore the order of each group. If any substring is not a valid
-regex, treat it as a literal string."
+Ignore the order of each group. If any substring is not a valid
+regex, treat it as a literal string.
+If DISCARD is non-nil, mark the regex as non-matching i.e. candidates
+should not match the regexp."
(let* ((subs (split-string str " +" t))
(len (length subs)))
(cl-case len
@@ -2136,8 +2144,8 @@ regex, treat it as a literal string."
(defun ivy--regex-ignore-order (str)
"Re-build regex from STR by splitting at spaces.
-Ignore the order of each group. Everything before \"!\" should
-match. Everything after \"!\" should not match."
+Ignore the order of each group. Everything before \"!\" should
+match. Everything after \"!\" should not match."
(let ((parts (split-string str "!" t)))
(cl-case (length parts)
(0
@@ -2156,7 +2164,7 @@ match. Everything after \"!\" should not match."
(defun ivy--regex-plus (str)
"Build a regex sequence from STR.
Spaces are wild card characters, everything before \"!\" should
-match. Everything after \"!\" should not match."
+match. Everything after \"!\" should not match."
(let ((parts (split-string str "!" t)))
(cl-case (length parts)
(0
@@ -2188,10 +2196,9 @@ Insert .* between each char."
str))
(defcustom ivy-fixed-height-minibuffer nil
- "When non nil, fix the height of the minibuffer during ivy
-completion at `ivy-height'. This effectively sets the minimum
-height at this level and tries to ensure that it does not change
-depending on the number of candidates."
+ "When non nil, fix the height of the minibuffer during ivy completion.
+This effectively sets the minimum height at this level to `ivy-height' and
+tries to ensure that it does not change depending on the number of candidates."
:group 'ivy
:type 'boolean)
@@ -2242,6 +2249,8 @@ Called with two arguments, PROMPT and STD-PROPS.
The returned value should be the updated PROMPT.")
(defun ivy-set-prompt-text-properties-default (prompt std-props)
+ "Set text properties of PROMPT.
+STD-PROPS is a property list containing the default text properties."
(ivy--set-match-props prompt "confirm"
`(face ivy-confirm-face ,@std-props))
(ivy--set-match-props prompt "match required"
@@ -2336,8 +2345,9 @@ The returned value should be the updated PROMPT.")
(constrain-to-field nil (point-max))))))
(defun ivy--set-match-props (str match props &optional subexp)
- "Set STR text properties for regexp group SUBEXP that match MATCH to PROPS.
-If SUBEXP is nil, the text properties are applied to the whole match."
+ "Set text properties of STR that match MATCH to PROPS.
+SUBEXP is a number which specifies the regexp group to use.
+If nil, the text properties are applied to the whole match."
(when (null subexp)
(setq subexp 0))
(when (string-match match str)
@@ -2374,10 +2384,12 @@ Possible choices are
'ivy-magic-slash-non-match-cd-selected,
nil)))
(defun ivy--create-and-cd (dir)
+ "When completing file names, create directory DIR and move there."
(make-directory dir)
(ivy--cd dir))
(defun ivy--magic-file-slash ()
+ "Handle slash when completing file names."
(when (or (and (eq this-command 'self-insert-command)
(eolp))
(eq this-command 'ivy-partial-or-done))
@@ -2681,7 +2693,7 @@ The alist VAL is a sorting function with the signature of
(defvar ivy--flx-featurep (require 'flx nil 'noerror))
(defun ivy--sort (name candidates)
- "Re-sort CANDIDATES by NAME.
+ "Re-sort candidates by NAME.
All CANDIDATES are assumed to match NAME."
(let ((key (or (ivy-state-caller ivy-last)
(when (functionp (ivy-state-collection ivy-last))
@@ -2697,7 +2709,8 @@ All CANDIDATES are assumed to match NAME."
candidates))))
(defun ivy--prefix-sort (name candidates)
- "Re-sort CANDIDATES.
+ "Re-sort candidates by NAME.
+All CANDIDATES are assumed to match NAME.
Prefix matches to NAME are put ahead of the list."
(if (or (string-match "^\\^" name) (string= name ""))
candidates
@@ -2716,7 +2729,8 @@ Prefix matches to NAME are put ahead of the list."
"Store the virtual buffers alist.")
(defun ivy-sort-function-buffer (name candidates)
- "Re-sort CANDIDATES, a list of buffer names that contain NAME.
+ "Re-sort candidates by NAME.
+CANDIDATES is a list of buffer names each containing NAME.
Sort open buffers before virtual buffers, and prefix matches
before substring matches."
(if (or (string-match "^\\^" name) (string= name ""))
@@ -2747,6 +2761,8 @@ before substring matches."
(nreverse res-virtual-noprefix)))))
(defun ivy--recompute-index (name re-str cands)
+ "Recompute index of selected candidate matching NAME.
+RE-STR is the regexp, CANDS are the current candidates."
(let* ((caller (ivy-state-caller ivy-last))
(func (or (and caller (cdr (assoc caller ivy-index-functions-alist)))
(cdr (assoc t ivy-index-functions-alist))
@@ -2783,6 +2799,8 @@ before substring matches."
ivy--index)))))
(defun ivy-recompute-index-swiper (_re-str cands)
+ "Recompute index of selected candidate when using `swiper'.
+CANDS are the current candidates."
(condition-case nil
(let ((tail (nthcdr ivy--index ivy--old-cands))
idx)
@@ -2808,6 +2826,8 @@ before substring matches."
(error 0)))
(defun ivy-recompute-index-swiper-async (_re-str cands)
+ "Recompute index of selected candidate when using `swiper' asynchronously.
+CANDS are the current candidates."
(if (null ivy--old-cands)
(let ((ln (with-ivy-window
(line-number-at-pos))))
@@ -2830,6 +2850,8 @@ before substring matches."
ivy--index))))
(defun ivy-recompute-index-zero (_re-str _cands)
+ "Recompute index of selected candidate.
+This function serves as a fallback when nothing else is available."
0)
(defcustom ivy-minibuffer-faces
@@ -2952,10 +2974,11 @@ This string is inserted into the minibuffer."
(- (length str) 3))) "...")
str))
-(defun ivy--format-function-generic (selected-fn other-fn strs separator)
- "Transform CAND-PAIRS into a string for minibuffer.
-SELECTED-FN and OTHER-FN each take one string argument.
-SEPARATOR is used to join the candidates."
+(defun ivy--format-function-generic (selected-fn other-fn cands separator)
+ "Transform candidates into a string for minibuffer.
+SELECTED-FN is called for the selected candidate, OTHER-FN for the others.
+Both functions take one string argument each. CANDS is a list of candidates
+and SEPARATOR is used to join them."
(let ((i -1))
(mapconcat
(lambda (str)
@@ -2963,11 +2986,11 @@ SEPARATOR is used to join the candidates."
(if curr
(funcall selected-fn str)
(funcall other-fn str))))
- strs
+ cands
separator)))
(defun ivy-format-function-default (cands)
- "Transform CAND-PAIRS into a string for minibuffer."
+ "Transform CANDS into a string for minibuffer."
(ivy--format-function-generic
(lambda (str)
(ivy--add-face str 'ivy-current-match))
@@ -2976,7 +2999,7 @@ SEPARATOR is used to join the candidates."
"\n"))
(defun ivy-format-function-arrow (cands)
- "Transform CAND-PAIRS into a string for minibuffer."
+ "Transform CANDS into a string for minibuffer."
(ivy--format-function-generic
(lambda (str)
(concat "> " (ivy--add-face str 'ivy-current-match)))
@@ -2986,7 +3009,7 @@ SEPARATOR is used to join the candidates."
"\n"))
(defun ivy-format-function-line (cands)
- "Transform CAND-PAIRS into a string for minibuffer."
+ "Transform CANDS into a string for minibuffer."
(ivy--format-function-generic
(lambda (str)
(ivy--add-face (concat str "\n") 'ivy-current-match))
@@ -2996,6 +3019,8 @@ SEPARATOR is used to join the candidates."
""))
(defun ivy-add-face-text-property (start end face str)
+ "Add face property to the text from START to END.
+FACE is the face to apply to STR."
(if (fboundp 'add-face-text-property)
(add-face-text-property
start end face nil str)
@@ -3058,6 +3083,7 @@ SEPARATOR is used to join the candidates."
str)
(defun ivy--format-minibuffer-line (str)
+ "Format line STR for use in minibuffer."
(if (eq ivy-display-style 'fancy)
(funcall ivy--highlight-function (copy-sequence str))
(copy-sequence str)))
@@ -3068,6 +3094,7 @@ SEPARATOR is used to join the candidates."
'read-file-name-internal 'ivy-read-file-transformer)
(defun ivy-read-file-transformer (str)
+ "Transform candidate STR when reading files."
(if (string-match-p "/\\'" str)
(propertize str 'face 'ivy-subdir)
str))
@@ -3163,7 +3190,9 @@ Each KEY is `major-mode', each VALUE is a face name.")
(defun ivy--buffer-list (str &optional virtual predicate)
"Return the buffers that match STR.
-When VIRTUAL is non-nil, add virtual buffers."
+If VIRTUAL is non-nil, add virtual buffers.
+If optional argument PREDICATE is non-nil, use it to test each
+possible match. See `all-completions' for further information."
(delete-dups
(append
(mapcar
@@ -3196,7 +3225,7 @@ When VIRTUAL is non-nil, add virtual buffers."
The default value is given as an example.
-Each element is a list of (NAME TREE). NAME is a string, it's
+Each element is a list of (NAME TREE). NAME is a string, it's
recommended to end it with a distinctive snippet e.g. \"{}\" so
that it's easy to distinguish the window configurations.
@@ -3209,6 +3238,7 @@ TREE is a nested list with the following valid cars:
TREE can be nested multiple times to have mulitple window splits.")
(defun ivy-default-view-name ()
+ "Return default name for new view."
(let* ((default-view-name
(concat "{} "
(mapconcat #'identity
@@ -3283,6 +3313,7 @@ Use `ivy-pop-view' to delete any item from `ivy-views'."
:caller 'ivy-pop-view))
(defun ivy-source-views ()
+ "Return the name of the views saved in `ivy-views'."
(mapcar #'car ivy-views))
(ivy-set-sources
@@ -3291,6 +3322,7 @@ Use `ivy-pop-view' to delete any item from `ivy-views'."
(ivy-source-views)))
(defun ivy-set-view-recur (view)
+ "Set VIEW recursively."
(cond ((eq (car view) 'vert)
(let* ((wnd1 (selected-window))
(wnd2 (split-window-vertically))
@@ -3397,7 +3429,7 @@ BUFFER may be a string or nil."
("w" (lambda (x) (kill-new (if (stringp x) x (car x)))) "copy")))
(defun ivy--switch-buffer-matcher (regexp candidates)
- "Return REGEXP-matching CANDIDATES.
+ "Return REGEXP matching CANDIDATES.
Skip buffers that match `ivy-ignore-buffers'."
(let ((res (ivy--re-filter regexp candidates)))
(if (or (null ivy-use-ignore)
@@ -3421,12 +3453,14 @@ Skip buffers that match `ivy-ignore-buffers'."
'internal-complete-buffer 'ivy-switch-buffer-transformer)
(defun ivy-append-face (str face)
+ "Append to STR the property FACE."
(let ((new (copy-sequence str)))
(font-lock-append-text-property
0 (length new) 'face face new)
new))
(defun ivy-switch-buffer-transformer (str)
+ "Transform candidate STR when switching buffers."
(let ((b (get-buffer str)))
(if (and b
(buffer-file-name b)
@@ -3435,7 +3469,7 @@ Skip buffers that match `ivy-ignore-buffers'."
str)))
(defun ivy-switch-buffer-occur ()
- "Occur function for `ivy-switch-buffer' that uses `ibuffer'."
+ "Occur function for `ivy-switch-buffer' using `ibuffer'."
(let* ((cand-regexp
(concat "\\(" (mapconcat #'regexp-quote ivy--old-cands "\\|") "\\)"))
(new-qualifier `((name . ,cand-regexp))))
@@ -3528,7 +3562,7 @@ The selected history element will be inserted into the
minibuffer."
(ivy--cd-maybe)))))
(defun ivy-restrict-to-matches ()
- "Restrict candidates to current matches and erase input."
+ "Restrict candidates to current input and erase input."
(interactive)
(delete-minibuffer-contents)
(setq ivy--all-candidates
@@ -3615,6 +3649,7 @@ When `ivy-calling' isn't nil, call `ivy-occur-press'."
(ivy-set-occur 'ivy-switch-buffer-other-window 'ivy-switch-buffer-occur)
(defun ivy--occur-insert-lines (cands)
+ "Insert CANDS into `ivy-occur' buffer."
(dolist (str cands)
(add-text-properties
0 (length str)
@@ -3627,7 +3662,7 @@ When `ivy-calling' isn't nil, call `ivy-occur-press'."
(forward-line 4))
(defun ivy-occur ()
- "Stop completion and put the current matches into a new buffer.
+ "Stop completion and put the current candidates into a new buffer.
The new buffer remembers current action(s).
@@ -3668,7 +3703,7 @@ There is no limit on the number of *ivy-occur* buffers."
(defun ivy-occur-revert-buffer ()
"Refresh the buffer making it up-to date with the collection.
-Currently only works for `swiper'. In that specific case, the
+Currently only works for `swiper'. In that specific case, the
*ivy-occur* buffer becomes nearly useless as the orignal buffer
is updated, since the line numbers no longer match.
@@ -3680,7 +3715,7 @@ updated original buffer."
(cond ((eq caller 'swiper)
(let ((buffer (ivy-state-buffer ivy-occur-last)))
(unless (buffer-live-p buffer)
- (error "buffer was killed"))
+ (error "Buffer was killed"))
(let ((inhibit-read-only t))
(erase-buffer)
(funcall (plist-get ivy--occurs-list caller) t)
@@ -3780,6 +3815,7 @@ EVENT gives the mouse position."
(run-at-time 1.0 nil 'swiper--cleanup))))))))
(defun ivy-occur-press-and-switch ()
+ "Execute action for the current candidate and switch window."
(interactive)
(ivy-occur-press)
(select-window (ivy--get-window ivy-occur-last)))
