From 7b2bbb973af86e62e21d65ea765452d42e813cb9 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Thu, 1 Feb 2018 20:04:54 -0500 Subject: [PATCH] Improve real-buffer function docstrings --- core/autoload/buffers.el | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/core/autoload/buffers.el b/core/autoload/buffers.el index 0d74fee1b..f18169674 100644 --- a/core/autoload/buffers.el +++ b/core/autoload/buffers.el @@ -8,7 +8,9 @@ tested. Should any of its function returns non-nil, the rest of the functions are -ignored and the buffer is considered real.") +ignored and the buffer is considered real. + +See `doom-real-buffer-p' for more information.") ;;;###autoload (defvar doom-unreal-buffer-functions @@ -18,11 +20,14 @@ unlike `doom-real-buffer-functions'. They are passed one argument: the buffer to be tested. Should any of these functions return non-nil, the rest of the functions are -ignored and the buffer is considered unreal.") +ignored and the buffer is considered unreal. + +See `doom-real-buffer-p' for more information.") ;;;###autoload (defvar-local doom-real-buffer-p nil - "If non-nil, this buffer should be considered real no matter what.") + "If non-nil, this buffer should be considered real no matter what. See +`doom-real-buffer-p' for more information.") ;;;###autoload (defvar doom-fallback-buffer "*scratch*" @@ -84,8 +89,14 @@ If no project is active, return all buffers." ;;;###autoload (defun doom-real-buffer-p (&optional buffer-or-name) - "Returns t if BUFFER-OR-NAME is a 'real' buffer. The criteria for a real -buffer is: + "Returns t if BUFFER-OR-NAME is a 'real' buffer. + +A real buffer is a useful buffer; a first class citizen in Doom. Real ones +should get special treatment, because we will be spending most of our time in +them. Unreal ones should be low-profile and easy to cast aside, so we can focus +on real ones. + +The exact criteria for a real buffer is: 1. A non-nil value for the buffer-local value of the `doom-real-buffer-p' variable OR