bug#31858: 27.0; doc of `window-toggle-side-windows'

[Drew Adams <drew.adams@oracle.com>]

> > The doc should say that the function deletes all side windows
> > of FRAME, or it restores all such previously deleted side windows.
> 
> Seems like it does say that?

Not in so many words.  You have to read carefully to figure
out just what's being toggled here: the presence/validity of
(all) side windows.

If the function were called `delete/restore-side-windows'
then there would be no problem.  The doc string would then
only need to make clear that this means _all_ side windows.
End of story.  We can guess what deleting and restoring a
window means.  But toggling a window?

When the name is "toggle" the doc should (explicitly) say
what it is that is toggled - what state/quality.  A name
such as `toggle-foo-visibility' makes clear that it is the
_visibility_ of a foo or foo's that gets toggled.

What's toggled here?  Surely it's not a "window" (unless
you want to explicitly define "toggling" a window to mean
what this function does).

Here, the name of the state that is toggled is (apparently)
the presence, or the existence, or (I guess) the "validity"
of side windows.  The paragraph you mention describes the
deletion and restoring action, but it doesn't name the
state/quality that is _toggled_.  That's all.

"toggle the _appearance_ of all side windows" sounds to
me like perhaps something about the appearance - _how_
it looks gets toggled.

In fact, IIUC it is the "validity" of the side windows
that gets toggled.  Not really their existence or their
appearance or their presences (in Lisp), but their
"validity".

I think the doc says that "deletion" of a window object
does not mean that the object no longer exists: it can
be restored.

Sounds similar to, say, overlays.  When we "delete" an
overlay we don't say that its "appearance" changes or is
"toggled".  We do carefully point out, just as we do for
windows, that the overlay object continues to exist etc.

We should use whatever the appropriate terminology is, for
windows.  I'm no expert on what term is best here.  A quick
reading of the window doc gave me the impression that the
term is "validity" - deleted window objects exist but are
not "valid".

  A “valid window” is one that is either live or internal.
  A valid window can be “deleted”, i.e., removed from its
  frame (*note Deleting Windows::); then it is no longer valid,
  but the Lisp object representing it might be still referenced
  from other Lisp objects.  A deleted window may be made valid
  again by restoring a saved window configuration (*note
  Window Configurations::). -- node `Basic Windows'

(That also defines what "deleting" a window means, BTW.
If the doc string pointed to that manual node, it wouldn't
hurt.)

All I can say is that saying that the side "_windows are
toggled_" doesn't make sense.  That's OK for a function
name, but not for an explanation.

Or if you really want to talk about "toggling a window" then
please add something like "toggling a window means...".

I guess that here it means just what I said: "the function
deletes all side windows ... or it restores all such
previously deleted side windows."

HTH.