emacs-28 ed9f554: Improve doc strings in tab-line.el

[Eli Zaretskii]

branch: emacs-28
commit ed9f5546aa71e0f187eaff1b2a9ccfe7772e9f5c
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve doc strings in tab-line.el
    
    * lisp/tab-line.el (tab-line-tab-name-function)
    (tab-line-tab-name-truncated-buffer, tab-line-tabs-mode-buffers)
    (tab-line-tabs-buffer-group-function)
    (tab-line-tabs-buffer-group-sort-function)
    (tab-line-tabs-buffer-groups, tab-line-tab-name-format-function)
    (tab-line-tab-name-format-default, tab-line-format-template)
    (tab-line-tab-face-inactive-alternating)
    (tab-line-tab-face-special, tab-line-tab-face-modified)
    (tab-line-format, tab-line-auto-hscroll, tab-line-hscroll-right)
    (tab-line-hscroll-left, tab-line-new-tab, tab-line-select-tab)
    (tab-line-switch-to-prev-tab, tab-line-switch-to-next-tab)
    (tab-line-close-tab-function, tab-line-close-tab)
    (tab-line-tab-context-menu, tab-line-context-menu)
    (tab-line-mode, tab-line-exclude-modes, tab-line-mode--turn-on):
    Add or fix doc strings.
---
 lisp/tab-line.el | 94 ++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 57 insertions(+), 37 deletions(-)

diff --git a/lisp/tab-line.el b/lisp/tab-line.el
index 78c06bb..5be9052 100644
--- a/lisp/tab-line.el
+++ b/lisp/tab-line.el
@@ -262,8 +262,9 @@ If nil, don't show it at all."
 
 (defcustom tab-line-tab-name-function #'tab-line-tab-name-buffer
   "Function to get a tab name.
-Function gets two arguments: tab to get name for and a list of tabs
-to display.  By default, use function `tab-line-tab-name'."
+The function is called with one or two arguments: the buffer or
+another object whose tab's name is requested, and, optionally,
+the list of all tabs."
   :type '(choice (const :tag "Buffer name"
                         tab-line-tab-name-buffer)
                  (const :tag "Truncated buffer name"
@@ -294,9 +295,9 @@ to `tab-line-tab-name-truncated-buffer'."
 (defvar tab-line-tab-name-ellipsis t)
 
 (defun tab-line-tab-name-truncated-buffer (buffer &optional _buffers)
-  "Generate tab name from BUFFER.
+  "Generate tab name from BUFFER, truncating it as needed.
 Truncate it to the length specified by `tab-line-tab-name-truncated-max'.
-Append ellipsis `tab-line-tab-name-ellipsis' in this case."
+If truncated, append ellipsis per `tab-line-tab-name-ellipsis'."
   (let ((tab-name (buffer-name buffer)))
     (if (< (length tab-name) tab-line-tab-name-truncated-max)
         tab-name
@@ -343,7 +344,7 @@ Used only for `tab-line-tabs-mode-buffers' and 
`tab-line-tabs-buffer-groups'.")
                                 (buffer-list)))))
 
 (defun tab-line-tabs-mode-buffers ()
-  "Return a list of buffers with the same major mode with current buffer."
+  "Return a list of buffers with the same major mode as the current buffer."
   (let ((mode major-mode))
     (seq-sort-by #'buffer-name #'string<
                  (seq-filter (lambda (b) (with-current-buffer b
@@ -351,12 +352,12 @@ Used only for `tab-line-tabs-mode-buffers' and 
`tab-line-tabs-buffer-groups'.")
                              (funcall tab-line-tabs-buffer-list-function)))))
 
 (defvar tab-line-tabs-buffer-group-function nil
-  "Function to put a buffer to the group.
-Takes a buffer as arg and should return a group name as string.
-When the return value is nil, filter out the buffer.")
+  "Function to add a buffer to the appropriate group of tabs.
+Takes a buffer as arg and should return a group name as a string.
+If the return value is nil, the buffer should be filtered out.")
 
 (defvar tab-line-tabs-buffer-group-sort-function nil
-  "Function to sort buffers in group.")
+  "Function to sort buffers in a group.")
 
 (defvar tab-line-tabs-buffer-groups-sort-function #'string<
   "Function to sort group names.")
@@ -364,7 +365,9 @@ When the return value is nil, filter out the buffer.")
 (defvar tab-line-tabs-buffer-groups mouse-buffer-menu-mode-groups
   "How to group various major modes together in the tab line.
 Each element has the form (REGEXP . GROUPNAME).
-If the major mode's name string matches REGEXP, use GROUPNAME instead.")
+If the major mode's name matches REGEXP, it belongs to GROUPNAME.
+The default is for each major mode to have a separate group
+named the same as the mode.")
 
 (defun tab-line-tabs-buffer-group-name (&optional buffer)
   (if (functionp tab-line-tabs-buffer-group-function)
@@ -460,8 +463,11 @@ variable `tab-line-tabs-function'."
 
 (defcustom tab-line-tab-name-format-function #'tab-line-tab-name-format-default
   "Function to format a tab name.
-Function gets two arguments: the tab and a list of all tabs, and
-should return the formatted tab name to display in the tab line."
+The function will be called two arguments: the tab whose name to format,
+and the list of all the tabs; it should return the formatted tab name
+to display in the tab line.
+The first argument could also be a different object, for example the buffer
+which the tab will represent."
   :type 'function
   :initialize 'custom-initialize-default
   :set (lambda (sym val)
@@ -471,6 +477,7 @@ should return the formatted tab name to display in the tab 
line."
   :version "28.1")
 
 (defun tab-line-tab-name-format-default (tab tabs)
+  "Default function to use as `tab-line-tab-name-format-function', which see."
   (let* ((buffer-p (bufferp tab))
          (selected-p (if buffer-p
                          (eq tab (window-buffer))
@@ -503,7 +510,8 @@ should return the formatted tab name to display in the tab 
line."
              mouse-face tab-line-highlight))))
 
 (defun tab-line-format-template (tabs)
-  "Template for displaying tab line for selected window."
+  "Template of the format for displaying tab line for selected window.
+This is used by `tab-line-format'."
   (let* ((separator (or tab-line-separator (if window-system " " "|")))
          (hscroll (window-parameter nil 'tab-line-hscroll))
          (strings
@@ -535,7 +543,8 @@ should return the formatted tab name to display in the tab 
line."
 
 (defun tab-line-tab-face-inactive-alternating (tab tabs face _buffer-p 
selected-p)
   "Return FACE for TAB in TABS with alternation.
-When TAB is an inactive buffer and is even-numbered, make FACE
+SELECTED-P non-nil means TAB is not the selected tab.
+When TAB is not selected and is even-numbered, make FACE
 inherit from `tab-line-tab-inactive-alternate'.  For use in
 `tab-line-tab-face-functions'."
   (when (and (not selected-p) (cl-evenp (cl-position tab tabs)))
@@ -543,8 +552,8 @@ inherit from `tab-line-tab-inactive-alternate'.  For use in
   face)
 
 (defun tab-line-tab-face-special (tab _tabs face buffer-p _selected-p)
-  "Return FACE for TAB according to whether it's special.
-When TAB is a non-file-backed buffer, make FACE inherit from
+  "Return FACE for TAB according to whether its buffer is special.
+When TAB is a non-file-visiting buffer, make FACE inherit from
 `tab-line-tab-special'.  For use in
 `tab-line-tab-face-functions'."
   (when (and buffer-p (not (buffer-file-name tab)))
@@ -552,7 +561,7 @@ When TAB is a non-file-backed buffer, make FACE inherit from
   face)
 
 (defun tab-line-tab-face-modified (tab _tabs face buffer-p _selected-p)
-  "Return FACE for TAB according to whether it's modified.
+  "Return FACE for TAB according to whether its buffer is modified.
 When TAB is a modified, file-backed buffer, make FACE inherit
 from `tab-line-tab-modified'.  For use in
 `tab-line-tab-face-functions'."
@@ -570,7 +579,7 @@ For use in `tab-line-tab-face-functions'."
 (defvar tab-line-auto-hscroll)
 
 (defun tab-line-format ()
-  "Template for displaying tab line for selected window."
+  "Format for displaying the tab line of the selected window."
   (let* ((tabs (funcall tab-line-tabs-function))
          (cache-key (list tabs
                           ;; handle buffer renames
@@ -598,7 +607,7 @@ For use in `tab-line-tab-face-functions'."
 
 (defcustom tab-line-auto-hscroll t
   "Allow or disallow automatic horizontal scrolling of the tab line.
-Non-nil means the tab line are automatically scrolled horizontally to make
+Non-nil means the tab lines are automatically scrolled horizontally to make
 the selected tab visible."
   :type 'boolean
   :group 'tab-line
@@ -694,12 +703,16 @@ the selected tab visible."
       (force-mode-line-update t))))
 
 (defun tab-line-hscroll-right (&optional arg event)
+  "Scroll the tab line ARG positions to the right.
+Interactively, ARG is the prefix numeric argument and defaults to 1."
   (interactive (list current-prefix-arg last-nonmenu-event))
   (let ((window (and (listp event) (posn-window (event-start event)))))
     (tab-line-hscroll arg window)
     (force-mode-line-update window)))
 
 (defun tab-line-hscroll-left (&optional arg event)
+  "Scroll the tab line ARG positions to the left.
+Interactively, ARG is the prefix numeric argument and defaults to 1."
   (interactive (list current-prefix-arg last-nonmenu-event))
   (let ((window (and (listp event) (posn-window (event-start event)))))
     (tab-line-hscroll (- (or arg 1)) window)
@@ -707,10 +720,10 @@ the selected tab visible."
 
 
 (defun tab-line-new-tab (&optional event)
-  "Add a new tab to the tab line.
-Usually is invoked by clicking on the plus-shaped button.
-But any switching to other buffer also adds a new tab
-corresponding to the switched buffer."
+  "Add a new tab to the selected-window's tab line.
+This command is usually invoked by clicking on the plus-shaped button
+on the tab line.  Switching to another buffer also adds a new tab
+corresponding to the new buffer shown in the window."
   (interactive (list last-nonmenu-event))
   (if (functionp tab-line-new-tab-choice)
       (funcall tab-line-new-tab-choice)
@@ -723,9 +736,9 @@ corresponding to the switched buffer."
         (tmm-prompt (mouse-buffer-menu-keymap))))))
 
 (defun tab-line-select-tab (&optional event)
-  "Switch to the selected tab.
+  "Switch to the buffer specified by the tab on which you click.
 This command maintains the original order of prev/next buffers.
-So for example, switching to a previous tab is equivalent to
+So, for example, switching to a previous tab is equivalent to
 using the `previous-buffer' command."
   (interactive "e")
   (let* ((posnp (event-start event))
@@ -771,7 +784,7 @@ when `tab-line-tabs-function' is 
`tab-line-tabs-window-buffers'."
   :version "28.1")
 
 (defun tab-line-switch-to-prev-tab (&optional event)
-  "Switch to the previous tab.
+  "Switch to the previous tab's buffer.
 Its effect is the same as using the `previous-buffer' command
 (\\[previous-buffer])."
   (interactive (list last-nonmenu-event))
@@ -795,7 +808,7 @@ Its effect is the same as using the `previous-buffer' 
command
             (switch-to-buffer buffer)))))))
 
 (defun tab-line-switch-to-next-tab (&optional event)
-  "Switch to the next tab.
+  "Switch to the next tab's buffer.
 Its effect is the same as using the `next-buffer' command
 (\\[next-buffer])."
   (interactive (list last-nonmenu-event))
@@ -820,9 +833,9 @@ Its effect is the same as using the `next-buffer' command
 
 
 (defcustom tab-line-close-tab-function 'bury-buffer
-  "Defines what to do on closing the tab.
+  "What to do upon closing a tab on the tab line.
 If `bury-buffer', put the tab's buffer at the end of the list of all
-buffers that effectively hides the buffer's tab from the tab line.
+buffers, which effectively hides the buffer's tab from the tab line.
 If `kill-buffer', kills the tab's buffer.
 When a function, it is called with the tab as its argument.
 This option is useful when `tab-line-tabs-function' has the value
@@ -835,9 +848,9 @@ This option is useful when `tab-line-tabs-function' has the 
value
 
 (defun tab-line-close-tab (&optional event)
   "Close the selected tab.
-Usually is invoked by clicking on the close button on the right side
-of the tab.  This command buries the buffer, so it goes out of sight
-from the tab line."
+This command is usually invoked by clicking on the close button on the
+right side of the tab.  This command buries the buffer, so it goes out of
+sight of the tab line."
   (interactive (list last-nonmenu-event))
   (let* ((posnp (and (listp event) (event-start event)))
          (window (and posnp (posn-window posnp)))
@@ -860,7 +873,7 @@ from the tab line."
       (force-mode-line-update))))
 
 (defun tab-line-tab-context-menu (&optional event)
-  "Pop up context menu for the tab."
+  "Pop up the context menu for a tab-line tab."
   (interactive "e")
   (let ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t))))
     (define-key-after menu [close]
@@ -868,7 +881,7 @@ from the tab line."
     (popup-menu menu event)))
 
 (defun tab-line-context-menu (&optional event)
-  "Pop up context menu for the tab line."
+  "Pop up the context menu for the tab line."
   (interactive "e")
   (let ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t))))
     (define-key-after menu [close]
@@ -878,13 +891,15 @@ from the tab line."
 
 ;;;###autoload
 (define-minor-mode tab-line-mode
-  "Toggle display of window tab line in the buffer."
+  "Toggle display of tab line in the windows displaying the current buffer."
   :lighter nil
   (setq tab-line-format (when tab-line-mode '(:eval (tab-line-format)))))
 
 (defcustom tab-line-exclude-modes
   '(completion-list-mode)
-  "List of major modes in which the tab line is not enabled."
+  "List of major modes for which the tab-line display is not enabled.
+Buffers under any of these major modes will not show the tab line in
+their windows, even if `global-tab-line-mode' is enabled."
   :type '(repeat symbol)
   :group 'tab-line
   :version "27.1")
@@ -893,7 +908,12 @@ from the tab line."
 (defvar-local tab-line-exclude nil)
 
 (defun tab-line-mode--turn-on ()
-  "Turn on `tab-line-mode'."
+  "Turn on `tab-line-mode' in all pertinent buffers.
+Temporary buffers, buffers whose names begin with a space, buffers
+under major modes that are either mentioned in `tab-line-exclude-mode'
+or have a non-nil `tab-line-exclude' property on their symbol,
+and buffers that have a non-nil buffer-local value
+of `tab-line-exclude', are exempt from `tab-line-mode'."
   (unless (or (minibufferp)
               (string-match-p "\\` " (buffer-name))
               (memq major-mode tab-line-exclude-modes)