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

[Eli Zaretskii]

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.

(Also, quite a few commands there lacked doc strings, which should be
avoided at all costs.  I fixed that today.)

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.

  (defun tab-bar--key-to-number (key)

This function needs at least to document the meaning of each value it
can return: nil, t, or a number.

  (defun tab-bar--event-to-item (posn)
    (if (posn-window posn)
        (let ((caption (car (posn-string posn))))
          (when caption
            (get-text-property 0 'menu-item caption)))

This function should document the possible return values and their
meaning.  It should also say something about the text property it
retrieves from posn-string, and how that property is used.

  (defun tab-bar--format-tab (tab i)
    "Format TAB using its index I and return the result as a string."

the doc string of this function is at least inaccurate, if not
incorrect: it doesn't (always) return a string.  Please document what
it does return and the meaning of the various forms of the value.

  (defun tab-bar--format-tab-group (tab i &optional current-p)

This function lacks any documentation of the value it returns; please
add some minimal docs.

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

  (defun tab-bar--tab (&optional frame)

Please add some minimal documentation of the return value.

  (defun tab-bar--current-tab (&optional tab frame)

  (defun tab-bar--current-tab-make (&optional tab)

  (defun tab-bar--current-tab-find (&optional tabs frame)

  (defun tab-bar--current-tab-index (&optional tabs frame)

  (defun tab-bar--tab-index (tab &optional tabs frame)

  (defun tab-bar--tab-index-by-name (name &optional tabs frame)

  (defun tab-bar--tab-index-recent (nth &optional tabs frame)

  (defun tab-bar--tabs-recent (&optional tabs frame)

These functions need at least some comment saying what each one of
them does.

  (defun tab-switcher-delete-from-list (tab)
    "Delete the window configuration from both lists."

Which "both lists"?

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

Thanks.


In GNU Emacs 28.0.60 (build 72, i686-pc-mingw32)
 of 2021-10-17 built on HOME-C4E4A596F7
Repository revision: 35920791df78400a36bf4420584bd8349ce9bbee
Repository branch: emacs-28
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
System Description: Microsoft Windows XP Service Pack 3 (v5.1.0.2600)

Configured using:
 'configure -C --prefix=/d/usr --with-wide-int --with-modules
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -gdwarf-4 -g3''

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NOTIFY
W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS XPM
ZLIB

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
rfc822 mml mml-sec epa derived epg rfc6068 epg-config gnus-util rmail
rmail-loaddefs auth-source cl-seq eieio eieio-core cl-macs
eieio-loaddefs password-cache json map text-property-search time-date
subr-x seq byte-opt gv bytecomp byte-compile cconv mm-decode mm-bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader cl-loaddefs
cl-lib sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils
iso-transl tooltip eldoc paren electric uniquify ediff-hook vc-hooks
lisp-float-type elisp-mode mwheel dos-w32 ls-lisp disp-table
term/w32-win w32-win w32-vars term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode
prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu
timer select scroll-bar mouse jit-lock font-lock syntax font-core
term/tty-colors frame minibuffer cl-generic cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms
cp51932 hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese composite emoji-zwj charscript charprop case-table
epa-hook jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice
button loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote threads w32notify w32 lcms2 multi-tty
make-network-process emacs)

Memory information:
((conses 16 56715 8028)
 (symbols 48 7801 1)
 (strings 16 21649 1976)
 (string-bytes 1 632631)
 (vectors 16 13631)
 (vector-slots 8 180039 9875)
 (floats 8 23 59)
 (intervals 40 266 93)
 (buffers 888 10))