avy.el: Fix checkdoc warnings

Fixes #212

avy.el

@@ -1064,9 +1064,10 @@ exist."
 
 (defun avy--generic-jump (regex window-flip style &optional beg end)
   "Jump to REGEX.
+The window scope is determined by `avy-all-windows'.
 When WINDOW-FLIP is non-nil, do the opposite of `avy-all-windows'.
 STYLE determines the leading char overlay style.
-BEG and END delimit the area where candidates are searched."
+BEG and END narrow the scope where candidates are searched."
   (let ((avy-all-windows
          (if window-flip
              (not avy-all-windows)
@@ -1105,7 +1106,9 @@ The window scope is determined by `avy-all-windows' (ARG negates it)."
 ;;;###autoload
 (defun avy-goto-char-2 (char1 char2 &optional arg beg end)
   "Jump to the currently visible CHAR1 followed by CHAR2.
-The window scope is determined by `avy-all-windows' (ARG negates it)."
+The window scope is determined by `avy-all-windows'.
+When ARG is non-nil, do the opposite of `avy-all-windows'.
+BEG and END narrow the scope where candidates are searched."
   (interactive (list (read-char "char 1: " t)
                      (read-char "char 2: " t)
                      current-prefix-arg
@@ -1125,7 +1128,9 @@ The window scope is determined by `avy-all-windows' (ARG negates it)."
 
 ;;;###autoload
 (defun avy-goto-char-2-above (char1 char2 &optional arg)
-  "Jump to the currently visible CHAR1 followed by CHAR2.
+  "Jump to the currently visible CHAR1 followed by CHAR2.
+This is a scoped version of `avy-goto-char-2', where the scope is
+the visible part of the current buffer up to point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char 1: " t)
@@ -1138,7 +1143,9 @@ the visible part of the current buffer up to point."
 
 ;;;###autoload
 (defun avy-goto-char-2-below (char1 char2 &optional arg)
-  "Jump to the currently visible CHAR1 followed by CHAR2.
+  "Jump to the currently visible CHAR1 followed by CHAR2.
+This is a scoped version of `avy-goto-char-2', where the scope is
+the visible part of the current buffer following point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char 1: " t)
@@ -1163,19 +1170,25 @@ the visible part of the current buffer following point."
       (isearch-done))))
 
 ;;;###autoload
-(defun avy-goto-word-0 (arg &optional beg end)
+(defun avy-goto-word-0 (arg &optional beg end)
+  "Jump to a word start.
+The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'.
 BEG and END narrow the scope where candidates are searched."
   (interactive "P")
   (avy-with avy-goto-word-0
     (avy--generic-jump avy-goto-word-0-regexp arg avy-style beg end)))
-
+
+(defun avy-goto-word-0-above (arg)
+  "Jump to a word start between window start and point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive "P")
   (avy-with avy-goto-word-0
     (avy-goto-word-0 arg (window-start) (point))))
-
+
+(defun avy-goto-word-0-below (arg)
+  "Jump to a word start between point and window end.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive "P")
@@ -1183,7 +1196,10 @@ The window scope is determined by `avy-all-windows' (ARG negates it)."
     (avy-goto-word-0 arg (point) (window-end (selected-window) t))))
 
 ;;;###autoload
-(defun avy-goto-word-1 (char &optional arg beg end symbol)
+(defun avy-goto-word-1 (char &optional arg beg end symbol)
+  "Jump to the currently visible CHAR at a word start.
+The window scope is determined by `avy-all-windows'.
+When ARG is non-nil, do the opposite of `avy-all-windows'.
 BEG and END narrow the scope where candidates are searched.
 When SYMBOL is non-nil, jump to symbol start instead of word start."
   (interactive (list (read-char "char: " t)
@@ -1205,7 +1221,9 @@ The window scope is determined by `avy-all-windows' (ARG negates it)."
 
 ;;;###autoload
 (defun avy-goto-word-1-above (char &optional arg)
-  "Jump to the currently visible CHAR at a word start.
+  "Jump to the currently visible CHAR at a word start.
+This is a scoped version of `avy-goto-word-1', where the scope is
+the visible part of the current buffer up to point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char: " t)
@@ -1215,7 +1233,9 @@ the visible part of the current buffer up to point. "
 
 ;;;###autoload
 (defun avy-goto-word-1-below (char &optional arg)
-  "Jump to the currently visible CHAR at a word start.
+  "Jump to the currently visible CHAR at a word start.
+This is a scoped version of `avy-goto-word-1', where the scope is
+the visible part of the current buffer following point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char: " t)
@@ -1224,7 +1244,8 @@ the visible part of the current buffer following point. "
     (avy-goto-word-1 char arg (point) (window-end (selected-window) t))))
 
 ;;;###autoload
-(defun avy-goto-symbol-1 (char &optional arg)
+(defun avy-goto-symbol-1 (char &optional arg)
+  "Jump to the currently visible CHAR at a symbol start.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char: " t)
@@ -1234,7 +1255,9 @@ The window scope is determined by `avy-all-windows' (ARG negates it)."
 
 ;;;###autoload
 (defun avy-goto-symbol-1-above (char &optional arg)
-  "Jump to the currently visible CHAR at a symbol start.
+  "Jump to the currently visible CHAR at a symbol start.
+This is a scoped version of `avy-goto-symbol-1', where the scope is
+the visible part of the current buffer up to point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char: " t)
@@ -1244,7 +1267,9 @@ the visible part of the current buffer up to point. "
 
 ;;;###autoload
 (defun avy-goto-symbol-1-below (char &optional arg)
-  "Jump to the currently visible CHAR at a symbol start.
+  "Jump to the currently visible CHAR at a symbol start.
+This is a scoped version of `avy-goto-symbol-1', where the scope is
+the visible part of the current buffer following point.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive (list (read-char "char: " t)
@@ -1323,6 +1348,10 @@ Which one depends on variable `subword-mode'."
     (call-interactively #'avy-goto-word-1)))
 
 (defvar visual-line-mode)
+
+(defun avy--line-cands (&optional arg beg end)
+  "Get candidates for selecting a line.
+The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'.
 BEG and END narrow the scope where candidates are searched."
   (let (candidates)
@@ -1346,6 +1375,7 @@ Which one depends on variable `subword-mode'."
                     (line-move-visual 1 t))
                 (forward-line 1)))))))
     (nreverse candidates)))
+
 (defun avy--linum-strings ()
   "Get strings for `avy-linum-mode'."
   (let* ((lines (mapcar #'car (avy--line-cands)))
@@ -1429,8 +1459,9 @@ Which one depends on variable `subword-mode'."
                       (frame-char-width)))))
     (set-window-margins win width (cdr (window-margins win)))))
 
-(defun avy--line (&optional arg beg end)
+(defun avy--line (&optional arg beg end)
-  "Select a line.
+  "Select a line.
+The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'.
 BEG and END narrow the scope where candidates are searched."
   (let ((avy-action #'identity))
@@ -1618,7 +1649,7 @@ The window scope is determined by `avy-all-windows' or
       (let* ((beg (save-selected-window
                     (list (avy--line arg) (selected-window))))
              (end (list (avy--line arg) (selected-window))))
-        (cond
+        (cond
           ((not (numberp (car beg)))
            (user-error "Fail to select the beginning of region"))
           ((not (numberp (car end)))
@@ -1640,7 +1671,9 @@ The window scope is determined by `avy-all-windows' or
               (car end)))))))
     (select-window initial-window)))
 
-;;;###autoload
+;;;###autoload
+(defun avy-kill-ring-save-region (arg)
+  "Select two lines and save the region between them to the kill ring.
 The window scope is determined by `avy-all-windows'.
 When ARG is non-nil, do the opposite of `avy-all-windows'."
   (interactive "P")
@@ -1649,7 +1682,7 @@ The window scope is determined by `avy-all-windows' or
       (let* ((beg (save-selected-window
                     (list (avy--line arg) (selected-window))))
              (end (list (avy--line arg) (selected-window))))
-        (cond
+        (cond
           ((not (numberp (car beg)))
            (user-error "Fail to select the beginning of region"))
           ((not (numberp (car end)))
@@ -1671,7 +1704,7 @@ The window scope is determined by `avy-all-windows' or
 ;;;###autoload
 (defun avy-kill-whole-line (arg)
   "Select line and kill the whole selected line.
-
+
 With a numerical prefix ARG, kill ARG line(s) starting from the
 selected line.  If ARG is negative, kill backward.
 
@@ -1693,10 +1726,16 @@ selected line."
                           (kill-whole-line arg)))))
     (select-window initial-window)))
 
-;;;###autoload
+;;;###autoload
 (defun avy-kill-ring-save-whole-line (arg)
   "Select line and save the whole selected line as if killed, but don’t kill it.
-
+
+This command is similar to `avy-kill-whole-line', except that it
+saves the line(s) as if killed, but does not kill it(them).
+
+With a numerical prefix ARG, kill ARG line(s) starting from the
+selected line.  If ARG is negative, kill backward.
+
 If ARG is zero, kill the selected line but exclude the trailing
 newline."
   (interactive "P")