From: Eli Zaretskii Date: Sun, 17 Oct 2021 09:49:04 +0000 (+0300) Subject: Improve doc strings in tab-line.el X-Git-Tag: emacs-28.0.90~271 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ed9f5546aa71e0f187eaff1b2a9ccfe7772e9f5c;p=emacs.git 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. --- diff --git a/lisp/tab-line.el b/lisp/tab-line.el index 78c06bbb64d..5be9052af4b 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)