branch: master
commit 082aaecf26091eeaae9d13a2738987cb04d590ad
Author: fabacino <[email protected]>
Commit: Oleh Krehel <[email protected]>
counsel.el: Fix checkdoc warnings
---
counsel.el | 200 +++++++++++++++++++++++++++++++++++++++----------------------
1 file changed, 127 insertions(+), 73 deletions(-)
diff --git a/counsel.el b/counsel.el
index 470e8b9..de8f7a4 100644
--- a/counsel.el
+++ b/counsel.el
@@ -51,6 +51,7 @@
(format "%d chars more" (- n (length ivy-text)))))
(defun counsel-unquote-regex-parens (str)
+ "Unquote regex parenthesis in STR."
(let ((start 0)
ms)
(while (setq start (string-match "\\\\)\\|\\\\(\\|[()]" str start))
@@ -68,7 +69,7 @@
(setq str (replace-match "\\)" nil t str))
(setq start (+ start 2)))
(t
- (error "unexpected"))))
+ (error "Unexpected"))))
str))
(defun counsel-directory-parent (dir)
@@ -95,8 +96,8 @@ Or the time of the last minibuffer update.")
Or the time of the last minibuffer update.")
(defvar counsel--async-duration nil
- "Store the time in seconds between starting a process and
- receiving all candidates.")
+ "Store the time a process takes to gather all its candidates.
+The time is measured in seconds.")
(defvar counsel--async-exit-code-plist nil
"Associates exit codes with reasons.")
@@ -114,6 +115,11 @@ Or the time of the last minibuffer update.")
"Store the regexp for splitting shell command output.")
(defun counsel--async-command (cmd &optional process-sentinel process-filter)
+ "Start new counsel process by calling CMD.
+If a counsel process is already running, kill it and its associated buffer
+before starting a new one. If non-nil, use PROCESS-SENTINEL as the sentinel
+function instead of `counsel--async-sentinel'. If non-nil, use PROCESS-FILTER
+for handling the output of the process instead of `counsel--async-filter'."
(let* ((counsel--process " *counsel*")
(proc (get-process counsel--process))
(buff (get-buffer counsel--process)))
@@ -133,6 +139,8 @@ Or the time of the last minibuffer update.")
(defvar counsel-grep-last-line nil)
(defun counsel--async-sentinel (process event)
+ "Sentinel function for an asynchronous counsel PROCESS.
+EVENT is a string describing the change."
(let ((cands
(cond ((string= event "finished\n")
(with-current-buffer (process-buffer process)
@@ -223,6 +231,7 @@ Update the minibuffer with the amount of lines collected
every
(format "%s: " (ivy-state-prompt ivy-last))))
(defun counsel-delete-process ()
+ "Delete current counsel process."
(let ((process (get-process " *counsel*")))
(when process
(delete-process process))))
@@ -359,7 +368,8 @@ Update the minibuffer with the amount of lines collected
every
;;;###autoload
(defun counsel-unicode-char (&optional count)
- "Insert a Unicode character at point."
+ "Insert COUNT copies of a Unicode character at point.
+COUNT defaults to 1."
(interactive "p")
(let ((minibuffer-allow-text-properties t)
(ivy-sort-max-size (expt 256 6)))
@@ -645,6 +655,7 @@ input corresponding to the chosen variable."
;;;###autoload
(defun counsel-file-register ()
+ "Search file in register."
(interactive)
(ivy-read "File Register: "
;; Use the `register-alist' variable to filter out file
@@ -673,9 +684,8 @@ input corresponding to the chosen variable."
(declare-function bookmark-location "bookmark")
(defcustom counsel-bookmark-avoid-dired nil
- "If non-nil, choosing a directory in `counsel-bookmark'
-forwards the choice to `counsel-find-file' instead of opening a
-dired buffer."
+ "If non-nil, open directory bookmarks with `counsel-find-file'.
+By default `counsel-bookmark' opens a dired buffer for directories."
:type 'boolean
:group 'ivy)
@@ -722,7 +732,7 @@ dired buffer."
(declare-function smex-rank "ext:smex")
(defun counsel--M-x-prompt ()
- "M-x plus the string representation of `current-prefix-arg'."
+ "String for `M-x' plus the string representation of `current-prefix-arg'."
(if (not current-prefix-arg)
"M-x "
(concat
@@ -882,6 +892,8 @@ Usable with `ivy-resume', `ivy-next-line-and-call' and
"History for `counsel-descbinds'.")
(defun counsel--descbinds-cands (&optional prefix buffer)
+ "Get key bindings starting with PREFIX in BUFFER.
+See `describe-buffer-bindings' for further information."
(let ((buffer (or buffer (current-buffer)))
(re-exclude (regexp-opt
'("<vertical-line>" "<bottom-divider>" "<right-divider>"
@@ -916,21 +928,28 @@ Usable with `ivy-resume', `ivy-next-line-and-call' and
(nreverse res)))
(defun counsel-descbinds-action-describe (x)
+ "Describe function of candidate X.
+See `describe-function' for further information."
(let ((cmd (cddr x)))
(describe-function cmd)))
(defun counsel-descbinds-action-find (x)
+ "Find symbol definition of candidate X.
+See `counsel--find-symbol' for further information."
(let ((cmd (cddr x)))
(counsel--find-symbol (symbol-name cmd))))
(defun counsel-descbinds-action-info (x)
+ "Display symbol definition of candidate X, as found in the relevant manual.
+See `info-lookup-symbol' for further information."
(let ((cmd (cddr x)))
(counsel-info-lookup-symbol (symbol-name cmd))))
;;;###autoload
(defun counsel-descbinds (&optional prefix buffer)
- "Show a list of all defined keys, and their definitions.
-Describe the selected candidate."
+ "Show a list of all defined keys and their definitions.
+If non-nil, show only bindings that start with PREFIX.
+BUFFER defaults to the current one."
(interactive)
(ivy-read "Bindings: " (counsel--descbinds-cands prefix buffer)
:action #'counsel-descbinds-action-describe
@@ -982,6 +1001,7 @@ Describe the selected candidate."
:caller 'counsel-git))))
(defun counsel-git-action (x)
+ "Find file X in current Git repository."
(with-ivy-window
(let ((default-directory counsel--git-dir))
(find-file x))))
@@ -1036,8 +1056,7 @@ Typical value: '(recenter)."
directory))))))
(defcustom counsel-git-grep-skip-counting-lines nil
- "If non-nil, total lines in the git repository will not be counted
- before grepping."
+ "If non-nil, don't count lines before grepping ina git repository."
:type 'boolean
:group 'ivy)
@@ -1055,6 +1074,7 @@ Typical value: '(recenter)."
nil))))
(defun counsel-git-grep-action (x)
+ "Go to occurrence X in current Git repository."
(when (string-match "\\`\\(.*?\\):\\([0-9]+\\):\\(.*\\)\\'" x)
(with-ivy-window
(let ((file-name (match-string-no-properties 1 x))
@@ -1070,6 +1090,7 @@ Typical value: '(recenter)."
(swiper--add-overlays (ivy--regex ivy-text)))))))
(defun counsel-git-grep-matcher (regexp candidates)
+ "Return REGEXP matching CANDIDATES for `counsel-git-grep'."
(or (and (equal regexp ivy--old-re)
ivy--old-cands)
(prog1
@@ -1163,6 +1184,7 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
:caller 'counsel-git-grep))))
(defun counsel-git-grep-proj-function (str)
+ "Grep for STR in the current git repository."
(if (< (length str) 3)
(counsel-more-chars 3)
(let ((regex (setq ivy--old-re
@@ -1208,6 +1230,8 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
#'counsel--gg-sentinel)))
(defun counsel--gg-sentinel (process event)
+ "Sentinel function for a `counsel-git-grep' PROCESS.
+EVENT is a string describing the change."
(if (member event '("finished\n"
"exited abnormally with code 141\n"))
(progn
@@ -1225,8 +1249,9 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
(ivy--exhibit)))))
(defun counsel--gg-count (regex &optional no-async)
- "Quickly and asynchronously count the amount of git grep REGEX matches.
-When NO-ASYNC is non-nil, do it synchronously."
+ "Count the number of results matching REGEX in `counsel-git-grep'.
+The command to count the matches is called asynchronously.
+If NO-ASYNC is non-nil, do it synchronously instead."
(let ((default-directory counsel--git-grep-dir)
(cmd
(concat
@@ -1309,6 +1334,7 @@ When REVERT is non-nil, regenerate the current
*ivy-occur* buffer."
(perform-replace from to t t nil)))))))))))
(defun counsel-git-grep-recenter ()
+ "Recenter window according to the selected candidate."
(interactive)
(with-ivy-window
(counsel-git-grep-action (ivy-state-current ivy-last))
@@ -1316,6 +1342,8 @@ When REVERT is non-nil, regenerate the current
*ivy-occur* buffer."
;;** `counsel-git-stash'
(defun counsel-git-stash-kill-action (x)
+ "Add git stash command to kill ring.
+The git command applies the stash entry where candidate X was found in."
(when (string-match "\\([^:]+\\):" x)
(kill-new (message (format "git stash apply %s" (match-string 1 x))))))
@@ -1339,6 +1367,7 @@ done") "\n" t)))
"Command used for \"git log\".")
(defun counsel-git-log-function (input)
+ "Search for INPUT in git log."
(if (< (length input) 3)
(counsel-more-chars 3)
;; `counsel--yank-pop-format-function' uses this
@@ -1351,6 +1380,7 @@ done") "\n" t)))
nil))
(defun counsel-git-log-action (x)
+ "Add candidate X to kill ring."
(message "%S" (kill-new x)))
(defcustom counsel-yank-pop-truncate-radius 2
@@ -1361,9 +1391,9 @@ done") "\n" t)))
;;** `counsel-git-change-worktree'
(autoload 'string-trim-right "subr-x")
(defun counsel-git-change-worktree-action (git-root-dir tree)
- "Find the corresponding file in the worktree located at TREE.
-
-The current buffer is assumed to be in a subdirectory of GIT-ROOT-DIR."
+ "Find the corresponding file in the worktree located at tree.
+The current buffer is assumed to be in a subdirectory of GIT-ROOT-DIR.
+TREE is the selected candidate."
(let* ((new-root-dir (counsel-git-worktree-parse-root tree))
(tree-filename (file-relative-name (buffer-file-name) git-root-dir))
(file-name (expand-file-name tree-filename new-root-dir)))
@@ -1377,6 +1407,7 @@ The current buffer is assumed to be in a subdirectory of
GIT-ROOT-DIR."
(delete "" (split-string (string-trim-right cmd-output) "\n"))))
(defun counsel-git-worktree-parse-root (tree)
+ "Return worktree from candidate TREE."
(substring tree 0 (string-match " " tree)))
;;;###autoload
@@ -1434,7 +1465,7 @@ The current buffer is assumed to be in a subdirectory of
GIT-ROOT-DIR."
:group 'ivy)
(defun counsel-find-file-as-root (x)
- "Find file with root privileges."
+ "Find file X with root privileges."
(let* ((host (file-remote-p x 'host))
(file-name (format "/%s:%s:%s"
counsel-root-command
@@ -1466,7 +1497,7 @@ The current buffer is assumed to be in a subdirectory of
GIT-ROOT-DIR."
These files are un-ignored if `ivy-text' matches them. The
common way to show all files is to start `ivy-text' with a dot.
-Example value: \"\\(?:\\`[#.]\\)\\|\\(?:[#~]\\'\\)\". This will hide
+Example value: \"\\(?:\\`[#.]\\)\\|\\(?:[#~]\\'\\)\". This will hide
temporary and lock files.
\\<ivy-minibuffer-map>
Choosing the dotfiles option, \"\\`\\.\", might be convenient,
@@ -1480,7 +1511,7 @@ but the leading dot is a lot faster."
(regexp :tag "Regex")))
(defun counsel--find-file-matcher (regexp candidates)
- "Return REGEXP-matching CANDIDATES.
+ "Return REGEXP matching CANDIDATES.
Skip some dotfiles unless `ivy-text' requires them."
(let ((res (ivy--re-filter regexp candidates)))
(if (or (null ivy-use-ignore)
@@ -1667,6 +1698,7 @@ string - the full shell command to run."
(ivy--regex input t))))
(defun counsel-locate-function (input)
+ "Call the \"locate\" shell command with INPUT."
(if (< (length input) 3)
(counsel-more-chars 3)
(counsel--async-command
@@ -1733,10 +1765,10 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
;;;###autoload
(defun counsel-file-jump (&optional initial-input initial-directory)
- "Jump to a file from a list of all files directories
-below the current one. INITIAL-INPUT can be given as the initial
-minibuffer input. INITIAL-DIRECTORY, if non-nil, is used as the
-root directory for search."
+ "Jump to a file below the current directory.
+List all files within the current directory or any of its subdirectories.
+INITIAL-INPUT can be given as the initial minibuffer input.
+INITIAL-DIRECTORY, if non-nil, is used as the root directory for search."
(interactive
(list nil
(when current-prefix-arg
@@ -1762,10 +1794,10 @@ root directory for search."
;;;###autoload
(defun counsel-dired-jump (&optional initial-input initial-directory)
- "Jump to a directory (in dired) from a list of all directories
-below the current one. INITIAL-INPUT can be given as the initial
-minibuffer input. INITIAL-DIRECTORY, if non-nil, is used as the
-root directory for search."
+ "Jump to a directory (in dired) below the current directory.
+List all subdirectories within the current directory.
+INITIAL-INPUT can be given as the initial minibuffer input.
+INITIAL-DIRECTORY, if non-nil, is used as the root directory for search."
(interactive
(list nil
(when current-prefix-arg
@@ -1788,9 +1820,9 @@ root directory for search."
map))
(defcustom counsel-ag-base-command "ag --nocolor --nogroup %s"
- "Format string to use in `counsel-ag-function' to construct the
-command. The %s will be replaced by optional extra ag arguments followed by the
-regex string. The default is \"ag --nocolor --nogroup %s\"."
+ "Format string to use in `counsel-ag-function' to construct the command.
+The %s will be replaced by optional extra ag arguments followed by the
+regex string. The default is \"ag --nocolor --nogroup %s\"."
:type 'string
:group 'ivy)
@@ -1799,8 +1831,8 @@ regex string. The default is \"ag --nocolor --nogroup
%s\"."
(ivy-set-display-transformer 'counsel-ag 'counsel-git-grep-transformer)
(defun counsel-ag-function (string base-cmd extra-ag-args)
- "Grep in the current directory for STRING.
-If non-nil, EXTRA-AG-ARGS string is appended to BASE-CMD."
+ "Grep in the current directory for STRING using BASE-CMD.
+If non-nil, append EXTRA-AG-ARGS to BASE-CMD."
(when (null extra-ag-args)
(setq extra-ag-args ""))
(if (< (length string) 3)
@@ -1829,10 +1861,10 @@ If non-nil, EXTRA-AG-ARGS string is appended to
BASE-CMD."
;;;###autoload
(defun counsel-ag (&optional initial-input initial-directory extra-ag-args
ag-prompt)
"Grep for a string in the current directory using ag.
- INITIAL-INPUT can be given as the initial minibuffer input.
- INITIAL-DIRECTORY, if non-nil, is used as the root directory for search.
- EXTRA-AG-ARGS string, if non-nil, is appended to `counsel-ag-base-command'.
- AG-PROMPT, if non-nil, is passed as `ivy-read' prompt argument. "
+INITIAL-INPUT can be given as the initial minibuffer input.
+INITIAL-DIRECTORY, if non-nil, is used as the root directory for search.
+EXTRA-AG-ARGS string, if non-nil, is appended to `counsel-ag-base-command'.
+AG-PROMPT, if non-nil, is passed as `ivy-read' prompt argument."
(interactive)
(when current-prefix-arg
(setq initial-directory
@@ -1888,15 +1920,15 @@ If non-nil, EXTRA-AG-ARGS string is appended to
BASE-CMD."
;;** `counsel-pt'
(defcustom counsel-pt-base-command "pt --nocolor --nogroup -e %s"
- "Used to in place of `counsel-ag-base-command' to search with
-pt using `counsel-ag'."
+ "Alternative to `counsel-ag-base-command' using pt."
:type 'string
:group 'ivy)
;;;###autoload
(defun counsel-pt (&optional initial-input)
"Grep for a string in the current directory using pt.
-This uses `counsel-ag' with `counsel-pt-base-command' replacing
+INITIAL-INPUT can be given as the initial minibuffer input.
+This uses `counsel-ag' with `counsel-pt-base-command' instead of
`counsel-ag-base-command'."
(interactive)
(let ((counsel-ag-base-command counsel-pt-base-command))
@@ -1904,8 +1936,7 @@ This uses `counsel-ag' with `counsel-pt-base-command'
replacing
;;** `counsel-rg'
(defcustom counsel-rg-base-command "rg -i --no-heading --line-number
--max-columns 150 --color never %s ."
- "Used to in place of `counsel-rg-base-command' to search with
-ripgrep using `counsel-rg'."
+ "Alternative to `counsel-ag-base-command' using ripgrep."
:type 'string
:group 'ivy)
@@ -1919,7 +1950,7 @@ ripgrep using `counsel-rg'."
INITIAL-INPUT can be given as the initial minibuffer input.
INITIAL-DIRECTORY, if non-nil, is used as the root directory for search.
EXTRA-RG-ARGS string, if non-nil, is appended to `counsel-rg-base-command'.
-RG-PROMPT, if non-nil, is passed as `ivy-read' prompt argument. "
+RG-PROMPT, if non-nil, is passed as `ivy-read' prompt argument."
(interactive
(list nil
(when current-prefix-arg
@@ -1967,8 +1998,7 @@ RG-PROMPT, if non-nil, is passed as `ivy-read' prompt
argument. "
;;** `counsel-grep'
(defcustom counsel-grep-base-command "grep -nE '%s' %s"
- "Format string to use in `cousel-grep-function' to construct
-the command."
+ "Format string to use in `cousel-grep-function' to construct the command."
:type 'string
:group 'ivy)
@@ -1985,6 +2015,7 @@ the command."
nil)))
(defun counsel-grep-action (x)
+ "Go to candidate X."
(with-ivy-window
(swiper--cleanup)
(let ((default-directory (file-name-directory counsel--git-grep-dir))
@@ -2158,6 +2189,7 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
(declare-function org-move-to-column "org-compat")
(defun counsel-org-change-tags (tags)
+ "Change tags of current org headline to TAGS."
(let ((current (org-get-tags-string))
(col (current-column))
level)
@@ -2192,6 +2224,7 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
(org-move-to-column col)))
(defun counsel-org--set-tags ()
+ "Set tags of current org headline to `counsel-org-tags'."
(counsel-org-change-tags
(if counsel-org-tags
(format ":%s:"
@@ -2204,6 +2237,10 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
(declare-function org-agenda-error "org-agenda")
(defun counsel-org-tag-action (x)
+ "Add tag X to `counsel-org-tags'.
+If X is already part of the list, remove it instead. Quit the selection if
+X is selected by either `ivy-done', `ivy-alt-done' or `ivy-immediate-done',
+otherwise continue prompting for tags."
(if (member x counsel-org-tags)
(progn
(setq counsel-org-tags (delete x counsel-org-tags)))
@@ -2240,6 +2277,7 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
(delete-minibuffer-contents)))))
(defun counsel-org-tag-prompt ()
+ "Return prompt for `counsel-org-tag'."
(format "Tags (%s): "
(mapconcat #'identity counsel-org-tags ", ")))
@@ -2258,7 +2296,7 @@ INITIAL-INPUT can be given as the initial minibuffer
input."
;;;###autoload
(defun counsel-org-tag ()
- "Add or remove tags in org-mode."
+ "Add or remove tags in `org-mode'."
(interactive)
(save-excursion
(if (eq major-mode 'org-agenda-mode)
@@ -2478,7 +2516,7 @@ The face can be customized through
`counsel-org-goto-face-style'."
;;** `counsel-mark-ring'
(defun counsel--pad (string length)
- "Pad string to length with spaces."
+ "Pad STRING to LENGTH with spaces."
(let ((padding (max 0 (- length (length string)))))
(concat string (make-string padding ?\s))))
@@ -2515,10 +2553,9 @@ The face can be customized through
`counsel-org-goto-face-style'."
(defun counsel-package ()
"Install or delete packages.
-Packages not currently installed have a \"+\"
-prepended. Selecting one of these will try to install
-it. Currently installed packages have a \"-\" prepended, and
-selecting one of these will delete the package.
+Packages not currently installed have a \"+\" prepended. Selecting one
+of these will try to install it. Currently installed packages have a
+\"-\" prepended, and selecting one of these will delete the package.
Additional Actions:
@@ -2538,6 +2575,7 @@ Additional Actions:
:caller 'counsel-package)))
(defun counsel-package-make-package-cell (pkg)
+ "Make candidate for package PKG."
(let* ((pkg-sym (car pkg))
(pkg-name (symbol-name pkg-sym)))
(cons (format "%s%s"
@@ -2546,6 +2584,7 @@ Additional Actions:
pkg)))
(defun counsel-package-action (pkg-cons)
+ "Delete or install package in PKG-CONS."
(let ((pkg (cadr pkg-cons)))
(if (package-installed-p pkg)
(package-delete
@@ -2568,7 +2607,8 @@ Additional Actions:
(browse-url url))))
(defun counsel--package-sort (a b)
- "Sort function for `counsel-package'."
+ "Sort function for `counsel-package'.
+A is the left hand side, B the right hand side."
(let* ((a (car a))
(b (car b))
(a-inst (equal (substring a 0 1) "+"))
@@ -2619,6 +2659,7 @@ Additional Actions:
;;** `counsel-yank-pop'
(defun counsel--yank-pop-truncate (str)
+ "Truncate STR for use in `counsel-yank-pop'."
(condition-case nil
(let* ((lines (split-string str "\n" t))
(n (length lines))
@@ -2647,6 +2688,7 @@ Additional Actions:
:type 'string)
(defun counsel--yank-pop-format-function (cand-pairs)
+ "Transform CAND-PAIRS into a string for `counsel-yank-pop'."
(ivy--format-function-generic
(lambda (str)
(mapconcat
@@ -2754,12 +2796,14 @@ PREFIX is used to create the key."
;;** `counsel-list-processes'
(defun counsel-list-processes-action-delete (x)
+ "Delete process X."
(delete-process x)
(setf (ivy-state-collection ivy-last)
(setq ivy--all-candidates
(delete x ivy--all-candidates))))
(defun counsel-list-processes-action-switch (x)
+ "Switch to buffer of process X."
(let* ((proc (get-process x))
(buf (and proc (process-buffer proc))))
(if buf
@@ -2768,7 +2812,7 @@ PREFIX is used to create the key."
;;;###autoload
(defun counsel-list-processes ()
- "Offer completion for `process-list'
+ "Offer completion for `process-list'.
The default action deletes the selected process.
An extra action allows to switch to the process buffer."
(interactive)
@@ -2814,8 +2858,7 @@ An extra action allows to switch to the process buffer."
;;;###autoload
(defun counsel-expression-history ()
"Select an element of `read-expression-history'.
-And insert it into the minibuffer. Useful during
-`eval-expression'"
+And insert it into the minibuffer. Useful during `eval-expression'."
(interactive)
(let ((enable-recursive-minibuffers t))
(ivy-read "Expr: " (delete-dups read-expression-history)
@@ -2824,6 +2867,7 @@ And insert it into the minibuffer. Useful during
;;** `counsel-shell-command-history'
;;;###autoload
(defun counsel-shell-command-history ()
+ "Browse shell command history."
(interactive)
(ivy-read "cmd: " shell-command-history
:action #'insert
@@ -2886,6 +2930,7 @@ And insert it into the minibuffer. Useful during
(declare-function semantic-fetch-tags "semantic")
(defun counsel-semantic-action (tag)
+ "Got to semantic TAG."
(with-ivy-window
(goto-char (semantic-tag-start tag))))
@@ -2908,6 +2953,7 @@ And insert it into the minibuffer. Useful during
;;** `counsel-outline'
(defun counsel-outline-candidates ()
+ "Return outline candidates."
(let (cands)
(save-excursion
(goto-char (point-min))
@@ -2920,6 +2966,7 @@ And insert it into the minibuffer. Useful during
(nreverse cands))))
(defun counsel-outline-action (x)
+ "Go to outline X."
(with-ivy-window
(goto-char (cdr x))))
@@ -3011,7 +3058,7 @@ And insert it into the minibuffer. Useful during
:type '(list directory))
(defcustom counsel-linux-app-format-function
'counsel-linux-app-format-function-default
- "Function to format linux application names the `counsel-linux-app' menu.
+ "Function to format Linux application names the `counsel-linux-app' menu.
The format function will be passed the application's name, comment, and command
as arguments."
:group 'counsel
@@ -3038,7 +3085,9 @@ as arguments."
"The function used to format the cached Linux application menu.")
(defun counsel-linux-app-format-function-default (name comment exec)
- "Default linux application name formatter."
+ "Default Linux application name formatter.
+NAME is the name of the application, COMMENT its comment and EXEC
+the command to launch it."
(format "% -45s: %s%s"
(propertize exec 'face 'font-lock-builtin-face)
name
@@ -3047,7 +3096,8 @@ as arguments."
"")))
(defun counsel-linux-app-format-function-name-first (name comment exec)
- "Format linux application names with the name (and comment) first."
+ "Format Linux application names with the NAME (and COMMENT) first.
+EXEC is the command to launch the application."
(format "%s%s (%s)"
name
(if comment
@@ -3056,7 +3106,7 @@ as arguments."
(propertize exec 'face 'font-lock-builtin-face)))
(defun counsel-linux-app-format-function-name-only (name comment _exec)
- "Format linux application names with the name (and comment) only."
+ "Format Linux application names with the NAME (and COMMENT) only."
(format "%s%s"
name
(if comment
@@ -3064,13 +3114,13 @@ as arguments."
"")))
(defun counsel-linux-app-format-function-command-only (_name _comment exec)
- "Display only the command (Exec field) when formatting linux application
names."
+ "Display only the command EXEC when formatting Linux application names."
exec)
(defun counsel-linux-apps-list-desktop-files ()
- "Return an alist of (desktop-name . desktop-file) pairs for all Linux
applications.
-
- This function always returns it's elements in a stable order."
+ "Return an alist of all Linux applications.
+Each list entry is a pair of (desktop-name . desktop-file).
+This function always returns its elements in a stable order."
(let ((hash (make-hash-table :test #'equal))
result)
(dolist (dir counsel-linux-apps-directories)
@@ -3084,9 +3134,10 @@ as arguments."
result))
(defun counsel-linux-apps-parse (desktop-entries-alist)
- "Parse the given alist of desktop entries ((id . file-name)).
-
-Any desktop entries that fail to parse are recorded in
`counsel-linux-apps-faulty'."
+ "Parse the given alist of Linux desktop entries.
+Each entry in DESKTOP-ENTRIES-ALIST is a pair of ((id . file-name)).
+Any desktop entries that fail to parse are recorded in
+`counsel-linux-apps-faulty'."
(let (result)
(setq counsel-linux-apps-faulty nil)
(dolist (entry desktop-entries-alist result)
@@ -3142,6 +3193,7 @@ Any desktop entries that fail to parse are recorded in
`counsel-linux-apps-fault
result))))))))
(defun counsel-linux-apps-list ()
+ "Return list of all Linux desktop applications."
(let* ((new-desktop-alist (counsel-linux-apps-list-desktop-files))
(new-files (mapcar 'cdr new-desktop-alist)))
(unless (and
@@ -3172,16 +3224,16 @@ Any desktop entries that fail to parse are recorded in
`counsel-linux-apps-fault
(let ((file (read-file-name "Open: ")))
(if file
(call-process "gtk-launch" nil nil nil desktop-shortcut file)
- (user-error "cancelled"))))
+ (user-error "Cancelled"))))
(defun counsel-linux-app-action-open-desktop (desktop-shortcut)
- "Open DESKTOP-SHORTCUT"
+ "Open DESKTOP-SHORTCUT."
(setq desktop-shortcut (cdr desktop-shortcut))
(let ((file
(cdr (assoc desktop-shortcut
(counsel-linux-apps-list-desktop-files)))))
(if file
(find-file file)
- (user-error "cancelled"))))
+ (user-error "Cancelled"))))
(ivy-set-actions
'counsel-linux-app
@@ -3540,6 +3592,7 @@ selected candidate."
(defvar counsel--faces-fmt nil)
(defun counsel--faces-format-function (cands)
+ "Transform CANDS into a string for `counsel-faces'."
(ivy--format-function-generic
(lambda (str)
(concat
@@ -3667,6 +3720,7 @@ candidate."
(irony-completion-candidates-async 'counsel-irony-callback))
(defun counsel-irony-callback (candidates)
+ "Callback function for Irony to search among CANDIDATES."
(interactive)
(let* ((symbol-bounds (irony-completion-symbol-bounds))
(beg (car symbol-bounds))
@@ -3681,6 +3735,7 @@ candidate."
:action 'ivy-completion-in-region-action)))
(defun counsel-irony-annotate (x)
+ "Make Ivy candidate from Irony candidate X."
(cons (concat (car x) (irony-completion-annotation x))
(car x)))
@@ -3742,12 +3797,11 @@ a symbol and how to search for them."
(pop-mark . counsel-mark-ring)))
(define-key map (vector 'remap (car binding)) (cdr binding)))
map)
- "Map for `counsel-mode'. Remaps built-in functions to counsel
-replacements.")
+ "Map for `counsel-mode'.
+Remaps built-in functions to counsel replacements.")
(defcustom counsel-mode-override-describe-bindings nil
- "Whether to override `describe-bindings' when `counsel-mode' is
-active."
+ "Whether to override `describe-bindings' when `counsel-mode' is active."
:group 'ivy
:type 'boolean)
