GNU bug report logs - #51247
28.0.60; Insufficient documentation of tab-bar.el internal functions

Previous Next

Full log

View this message in rfc822 format

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 51247 <at> debbugs.gnu.org
Subject: bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions
Date: Sun, 17 Oct 2021 21:29:21 +0300

>    (defun tab-bar--current-tab-make (&optional tab)
>   -  ;; `tab' here is an argument meaning "use tab as template".  This is
>   -  ;; necessary when switching tabs, otherwise the destination tab
>   -  ;; inherits the current tab's `explicit-name' parameter.
>   +  "Make the current tab data structure from TAB.
>   +TAB here is an argument meaning \"use tab as template\".  This is
>   +necessary when switching tabs, otherwise the destination tab
>   +inherits the current tab's `explicit-name' parameter."
>
> I don't think I understand what do you mean by "use tab as template",
> can you explain?

Actually, "use tab as template" was not my text, but I improved it anyway,
together with all your suggestions.

>>   [ ] tab-bar-format-tabs
>>           Show all tabs.
>>   [X] tab-bar-format-tabs-groups
>>           Show tabs with their groups.
>>   [ ] tab-bar-separator
>>           Separator between tabs.
>>   [ ] tab-bar-format-add-tab
>>           Button to add a new tab.
>>   [X] tab-bar-format-align-right
>>           Align the rest of tab bar items to the right.
>>   [X] tab-bar-format-global
>>           Format ‘global-mode-string’ to display it in the tab bar. More
>>   [INS]
>>
>> So here its docstring explains what this option is useful for.
>
> Can't you provide a separate text for the Custom display?  The doc
> string in its current form is simply misleading.

It's a feature of :options in defcustom that it takes the text
from the docstrings.  Maybe it's possible to override this text,
but I currently don't know how.

>> >   (defun switch-to-buffer-other-tab (buffer-or-name &optional norecord)
>> >     "Switch to buffer BUFFER-OR-NAME in another tab.
>> >   Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab.
>> >   Interactively, prompt for the buffer to switch to."
>> >
>> > This command should document the NORECORD argument.
>>
>> Oops, this was copy/paste from switch-to-buffer, switch-to-buffer-other-window,
>> switch-to-buffer-other-frame that all just pass NORECORD down to 'pop-to-buffer'.
>> But switch-to-buffer-other-tab doesn't use 'pop-to-buffer'.  It uses 'display-buffer'
>> that has no NORECORD arg.  So this arg should be obsoleted, or maybe deleted right away.
>
> Fine with me, please use advertised-calling-convention or somesuch to
> hide that argument.

Done.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.