[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal fu
From: |
Juri Linkov |
Subject: |
bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions |
Date: |
Sun, 17 Oct 2021 20:17:43 +0300 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (x86_64-pc-linux-gnu) |
> 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.
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions,
Juri Linkov <=
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Juri Linkov, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Juri Linkov, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Juri Linkov, 2021/10/17
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/18
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Juri Linkov, 2021/10/18
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Eli Zaretskii, 2021/10/18
- bug#51247: 28.0.60; Insufficient documentation of tab-bar.el internal functions, Juri Linkov, 2021/10/18