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

Previous Next

Full log

Message #8 received at 51247 <at> debbugs.gnu.org (full text, mbox):

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

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

Previous Next

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