Re: [PATCH] Document tab opening/closing hooks and variables

[Robert Cochran <robert-emacs@cochranmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1244 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Cochran <robert-emacs@cochranmail.com>
>> Date: Tue, 10 Dec 2019 13:33:27 -0800
>> 
>> As promised, I've written information on tab-bar-post-open-functions,
>> tab-bar-close-last-tab-choice, tab-bar-prevent-close-functions, and
>> tab-bar-post-close-functions in the manual.
>> 
>> Suggestions and comments welcome, as usual.
>
> Thanks.
>
> I wonder whether such facilities need to be described in the manual.
> They sound pretty minor features, so perhaps we should let users
> discover them via Custom, doc strings, and NEWS?

I put them in the manual because I said that I would. I can't speak for
everyone, but sometimes stuff like that is nice to have in the manual. I
don't often discover variables via custom, but that might be because I
generally have a specific thing I have in mind I want to change when I
use it.

Such a thing definitely should be mentioned in the docstrings for the
functions, which I entirely forgot to write in both this patch and the
last patch. Oops. Here's a rough patch for that.

I think if anything else, that putting a couple of mentions in the
docstrings of some of the entry point functions is a reasonable
compromise.

Thanks,
-- 
~Robert Cochran


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Document tab-affecting variables in docstrings --]
[-- Type: text/x-patch, Size: 1961 bytes --]

From c6c4ae57b985bf9bd604613a173819fe725df761 Mon Sep 17 00:00:00 2001
From: Robert Cochran <robert-git@cochranmail.com>
Date: Wed, 11 Dec 2019 10:04:06 -0800
Subject: [PATCH] Document variables that affect tabs in function docstrings

* lisp/tab-bar.el (tab-bar-new-tab-to): Mention
tab-bar-post-open-functions in docstring.
(tab-bar-close-tab): Mention tab-bar-prevent-tab-functions,
tab-bar-tab-pre-close-functions, and tab-bar-close-last-tab-choice.
---
 lisp/tab-bar.el | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index ba4bc0afcd..7e8f56de2a 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -704,7 +704,10 @@ tab-bar-tab-post-open-functions
 (defun tab-bar-new-tab-to (&optional to-index)
   "Add a new tab at the absolute position TO-INDEX.
 TO-INDEX counts from 1.  If no TO-INDEX is specified, then add
-a new tab at the position specified by `tab-bar-new-tab-to'."
+a new tab at the position specified by `tab-bar-new-tab-to'.
+
+After the tab is created, the hooks in
+`tab-bar-tab-post-open-functions' are run."
   (interactive "P")
   (let* ((tabs (funcall tab-bar-tabs-function))
          (from-index (tab-bar--current-tab-index tabs))
@@ -819,7 +822,14 @@ tab-bar-close-tab
 Optional TO-INDEX could be specified to override the value of
 `tab-bar-close-tab-select' programmatically with a position
 of an existing tab to select after closing the current tab.
-TO-INDEX counts from 1."
+TO-INDEX counts from 1.
+
+The functions in `tab-bar-tab-prevent-close-functions' will be
+run to determine whether or not to close the tab.
+Just before the tab is closed, the functions in
+`tab-bar-tab-pre-close-functions' will be run.  The base behavior
+for the last tab on a frame is determined by
+`tab-bar-close-last-tab-choice'."
   (interactive "P")
   (let* ((tabs (funcall tab-bar-tabs-function))
          (current-index (tab-bar--current-tab-index tabs))
-- 
2.23.0