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

[Juri Linkov]

> Some functions in tab-bar.el and the data they return are documented
> insufficiently, so much so that it makes the code there very hard to
> develop and maintain by anyone except the original author.  Internal
> functions and data strictures don't need to have doc strings, but they
> do have to be explained enough for anyone to understand and modify the
> code without the need to step through it with a debugger.

It was on my TODO list to add docstrings to new functions
after their names and a list of arguments stabilizes.
For example, there was a need to rename some functions now in bug#51246.

> I show below the places where IMO the lack of proper documentation is
> particularly evident, or where the documentation is insufficient or
> inaccurate.  Please fill at least those gaps; bonus points for
> documenting more than this bare minimum.

I fixed all places that you noticed (please check), except the following:

>   (defun tab-bar-format-tabs-groups ()
>     "Show tabs with their groups."
>
> The doc string says "show", but this functions doesn't display
> anything, AFAICT, it produces a list.  Please adjust the doc string
> and add a description of the returned value.

This docstring is automatically displayed in the Customization buffer
of `tab-bar-format' that looks like this:

  Hide Tab Bar Format:
  Hook:
  [ ] tab-bar-format-menu-global
          Show global menu on clicking the Menu button.
  [X] tab-bar-format-history
          Show back and forward buttons when ‘tab-bar-history-mode’ is enabled. 
More
  [ ] 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.

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