bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions

[Juri Linkov]

>    (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.