Add arrow prefix + full line candidate format

* ivy.el (ivy-format-function-arrow-line): New candidate formatting
function.
(ivy-format-functions-alist): List it as one of the options.
(ivy-format-function-default, ivy-format-function-arrow)
(ivy-format-function-line): Extend docstrings.

Closes #2921.

Author: basil-conto

ivy.el

@@ -1706,6 +1706,8 @@ This string is inserted into the minibuffer."
            (const :tag "Default" ivy-format-function-default)
            (const :tag "Arrow prefix" ivy-format-function-arrow)
            (const :tag "Full line" ivy-format-function-line)
+           (const :tag "Arrow prefix + full line"
+                  ivy-format-function-arrow-line)
            (function :tag "Custom function"))))
 
 (defun ivy-sort-file-function-default (x y)
@@ -3967,7 +3969,8 @@ and SEPARATOR is used to join them."
      separator)))
 
 (defun ivy-format-function-default (cands)
-  "Transform CANDS into a string for minibuffer."
+  "Transform CANDS into a multiline string for the minibuffer.
+Add the face `ivy-current-match' to the selected candidate."
   (ivy--format-function-generic
    (lambda (str)
      (ivy--add-face str 'ivy-current-match))
@@ -3976,7 +3979,9 @@ and SEPARATOR is used to join them."
    "\n"))
 
 (defun ivy-format-function-arrow (cands)
-  "Transform CANDS into a string for minibuffer."
+  "Transform CANDS into a multiline string for the minibuffer.
+Like `ivy-format-function-default', but also prefix the selected
+candidate with an arrow \">\"."
   (ivy--format-function-generic
    (lambda (str)
      (concat "> " (ivy--add-face str 'ivy-current-match)))
@@ -3986,9 +3991,13 @@ and SEPARATOR is used to join them."
    "\n"))
 
 (defun ivy-format-function-line (cands)
-  "Transform CANDS into a string for minibuffer.
-Note that since Emacs 27, `ivy-current-match' needs to have :extend t attribute.
-It has it by default, but the current theme also needs to set it."
+  "Transform CANDS into a multiline string for the minibuffer.
+Like `ivy-format-function-default', but extend highlighting of
+the selected candidate to the window edge.
+
+Note that since Emacs 27, `ivy-current-match' needs to have a
+non-nil :extend attribute.  This is the case by default, but it
+also needs to be preserved by the current theme."
   (ivy--format-function-generic
    (lambda (str)
      (ivy--add-face (concat str "\n") 'ivy-current-match))
@@ -3997,6 +4006,18 @@ It has it by default, but the current theme also needs to set it."
    cands
    ""))
 
+(defun ivy-format-function-arrow-line (cands)
+  "Transform CANDS into a multiline string for the minibuffer.
+This combines the \">\" prefix of `ivy-format-function-arrow'
+with the extended highlighting of `ivy-format-function-line'."
+  (ivy--format-function-generic
+   (lambda (str)
+     (concat "> " (ivy--add-face (concat str "\n") 'ivy-current-match)))
+   (lambda (str)
+     (concat "  " str "\n"))
+   cands
+   ""))
+
 (defun ivy--highlight-ignore-order (str)
   "Highlight STR, using the ignore-order method."
   (when (consp ivy--old-re)