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

[Eli Zaretskii <eliz@gnu.org>]

> From: Juri Linkov <juri@linkov.net>
> Cc: 51247@debbugs.gnu.org
> Date: Mon, 18 Oct 2021 19:44:31 +0300
> 
> >> This text is still wrong:
> >>
> >>   Adding a function to the list causes the tab bar to show
> >>   that string, or display a menu with those menu items when
> >>   you click on the tab bar.
> >>
> >> The tab called "Menu" displays menu items from the global menu-bar,
> >> not from those menu items mentioned in the doc string.
> >> Those menu items are used only to display tabs.
> >
> > Then please point me to a function out of those mentioned in
> > tab-bar-format's :options that returns a list of menu items.  The
> > sentence in the doc string "Every item in the list is a function that
> > returns a string, or a list of menu-item elements, or nil" wasn't
> > mine, it was yours.  What did you have in mind when you wrote that?
> 
> - tab-bar-format-menu-global returns a list of menu items
>   that display the "Menu" tab.  This tab is bound to a command
>   that uses popup-menu to display the global menu on clicking.
> 
> - tab-bar-format-history returns a list of menu items
>   that produce back and forward buttons.
> 
> - tab-bar-format-tabs and tab-bar-format-tabs-groups
>   return a list of menu items that produce the tabs for the tab bar.
> ...
> 
> - Only tab-bar-separator returns a string.

Then the doc string after my changes is exactly right.  I have no idea
what you see that's wrong with it.  You say some functions return menu
items and some return a list of menu items, and that's what the doc
string says.  You say that these values are displayed on the tab bar,
and that's what the doc string says.  So what exactly is wrong??