bug#54865: 29.0.50; Unclear docstring 'switch-to-buffer'

[dalanicolai]

The docstring of `switch-to-buffer` states:

"If BUFFER-OR-NAME is a string that does not identify an existing
buffer, create a buffer with that name."

However, this is only true when called interactively. Although the
previous paragraph is about interactive use, to me, it is not clear that
the 'relevant' paragraph is still only about interactive use.
(for example, I assume that the next paragraph about the NORECORD argument is about general use)

It is no critical bug, but at least I guess it is nice to have it reported.


In GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.31, cairo version 1.17.4)
 of 2022-01-29 built on fedora
Repository revision: 96533c18b7f9d75dce9e6bb534a16ed4ccf44ad1
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12014000
System Description: Fedora Linux 35 (Workstation Edition)

Configured using:
 'configure --with-modules --with-cairo --with-native-compilation
 --with-json'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBXML2 MODULES NATIVE_COMP NOTIFY INOTIFY PDUMPER PNG RSVG
SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM XPM
GTK3 ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Help

Minor modes in effect:
  marginalia-mode: t
  savehist-mode: t
  vertico-mode: t
  global-evil-surround-mode: t
  evil-surround-mode: t
  recentf-mode: t
  shell-dirtrack-mode: t
  evil-mode: t
  evil-local-mode: t
  windmove-mode: t
  global-undo-tree-mode: t
  undo-tree-mode: t
  override-global-mode: t
  tooltip-mode: t
  global-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
  buffer-read-only: 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 yank-media rmc rfc822 mml
mml-sec epa epg rfc6068 epg-config gnus-util mm-decode mm-bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr shortdoc debug backtrace
find-func imenu cl-print help-fns radix-tree image-mode dired
dired-loaddefs exif mule-util time-date cursor-sensor consult-vertico
consult bookmark pp format-all language-id inheritenv gitter derived
pcase let-alist posframe transient format-spec request autorevert
filenotify mail-utils notifications dbus avy shr-tag-pre-highlight
language-detection shr text-property-search pixel-fill kinsoku puny svg
xml ewoc marginalia savehist orderless vertico evil-surround
evil-nerd-commenter evil-nerd-commenter-operator evil-nerd-commenter-sdk
sgml-mode facemenu dom which-key bind-map recentf tree-widget wid-edit
evil evil-keybindings evil-integration evil-maps evil-commands reveal
flyspell ispell evil-jumps evil-command-window evil-types evil-search
evil-ex shell pcomplete comint ansi-color evil-macros evil-repeat
evil-states evil-core comp comp-cstr warnings rx advice evil-common
windmove thingatpt rect evil-digraphs evil-vars ring edmacro kmacro
undo-tree diff cl-extra help-mode use-package use-package-ensure
use-package-delight use-package-diminish use-package-bind-key bind-key
easy-mmode use-package-core finder-inf info package browse-url url
url-proxy url-privacy url-expand url-methods url-history url-cookie
url-domsuf url-util mailcap url-handlers url-parse auth-source cl-seq
eieio eieio-core cl-macs eieio-loaddefs password-cache json map url-vars
seq gv subr-x byte-opt bytecomp byte-compile cconv cl-loaddefs cl-lib
chemacs iso-transl tooltip eldoc paren electric uniquify ediff-hook
vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd 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 keymap
hashtable-print-readable backquote threads dbusbind inotify
dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit x multi-tty make-network-process
native-compile emacs)

Memory information:
((conses 16 384898 29104)
 (symbols 48 23623 0)
 (strings 32 128809 5607)
 (string-bytes 1 4615770)
 (vectors 16 228260)
 (vector-slots 8 1475141 114223)
 (floats 8 91020 141)
 (intervals 56 1457 297)
 (buffers 992 16))