emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update+improve doom buffer library docstrings

Browse source
This commit is contained in:
Henrik Lissner 2017-09-24 19:18:26 +02:00
parent 78db91bdd2
commit 51fa99996d
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
1 changed files with 26 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

38
core/autoload/buffers.el
View file

@ -136,9 +136,19 @@ buffers. If there's nothing left, switch to `doom-fallback-buffer'. See
;;;###autoload
(defun doom-real-buffer-p (&optional buffer-or-name)
"Returns t if BUFFER-OR-NAME is a 'real' buffer. Real means it a) isn't a
popup window/buffer and b) isn't a special buffer."
(let ((buf (window-normalize-buffer buffer-or-name)))
"Returns t if BUFFER-OR-NAME is a 'real' buffer. The complete criteria for a
real buffer is:
1. The buffer-local value of `doom-real-buffer-p' (variable) is non-nil OR
2. Any function in `doom-real-buffer-functions' must return non-nil when
passed this buffer OR
3. The current buffer:
a) has a `buffer-file-name' defined AND
b) is not in a popup window (see `doom-popup-p') AND
c) is not a special buffer (its name isn't something like *Help*)
If BUFFER-OR-NAME is omitted or nil, the current buffer is tested."
(when-let (buf (ignore-errors (window-normalize-buffer buffer-or-name)))
(or (buffer-local-value 'doom-real-buffer-p buf)
(run-hook-with-args-until-success 'doom-real-buffer-functions buf)
(not (or (doom-popup-p buf)
@ -148,14 +158,14 @@ popup window/buffer and b) isn't a special buffer."
;;;###autoload
(defun doom/next-buffer ()
"Switch to the next real buffer, skipping special buffers. See
"Switch to the next real buffer, skipping non-real buffers. See
`doom-real-buffer-p' for what 'real' means."
(interactive)
(doom--cycle-real-buffers +1))
;;;###autoload
(defun doom/previous-buffer ()
"Switch to the previous real buffer, skipping special buffers. See
"Switch to the previous real buffer, skipping non-real buffers. See
`doom-real-buffer-p' for what 'real' means."
(interactive)
(doom--cycle-real-buffers -1))
@ -163,7 +173,10 @@ popup window/buffer and b) isn't a special buffer."
;;;###autoload
(defun doom-kill-buffer (&optional buffer dont-save)
"Kill BUFFER (falls back to current buffer if omitted) then switch to a real
buffer, but only bury the buffer if it is present in another window.
buffer. If the buffer is present in another window, only bury it.
Will prompt to save unsaved buffers when attempting to kill them, unless
DONT-SAVE is non-nil.
See `doom-real-buffer-p' for what 'real' means."
(setq buffer (or buffer (current-buffer)))
@ -250,9 +263,10 @@ regex PATTERN. Returns the number of killed buffers."
;;;###autoload
(defun doom/kill-all-buffers (&optional project-p)
"Kill all buffers.
"Kill all buffers and closes their windows.
If PROJECT-P, kill all buffers that belong to the current project."
If PROJECT-P (universal argument), kill only buffers that belong to the current
project."
(interactive "P")
(doom/popup-close-all t)
(let ((buffers (if project-p (doom-project-buffer-list) (doom-buffer-list))))
@ -263,10 +277,10 @@ If PROJECT-P, kill all buffers that belong to the current project."
;;;###autoload
(defun doom/kill-other-buffers (&optional project-p)
"Kill all other buffers.
"Kill all other buffers (besides the current one).
If PROJECT-P (universal argument), kill only the other buffers that belong to
the current project."
If PROJECT-P (universal argument), kill only buffers that belong to the current
project."
(interactive "P")
(let ((buffers (if project-p (doom-project-buffer-list) (doom-buffer-list)))
(current-buffer (current-buffer)))
@ -292,7 +306,7 @@ project."
;;;###autoload
(defun doom/cleanup-buffers (&optional all-p)
"Clean up buried and process buffers in the current workspace."
"Clean up buried and inactive process buffers in the current workspace."
(interactive "P")
(let ((buffers (doom-buried-buffers (if all-p (buffer-list))))
(n 0))