bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions

[Drew Adams]

This node has a list of functions and macros, some of which have
footnotes.  I don't understand the footnotes (which are not sentences,
BTW).

For example, `cl-incf' has footnote [1], which says:

 [1] Only when PLACE is a plain variable name.

What happens only when PLACE (the first arg to `cl-incf') is a plain
variable name?  What happens when PLACE is not a plain variable name?

`C-h f cl-incf' doesn't help at all in this regard.  It doesn't say
anything at all about different behaviors for different kinds of PLACE.

Similarly for the other names and their footnotes.

There's no doc specifying the behaviors of `cl-pushnew' etc. for any
particular kinds of PLACE.  Nothing says what happens "only if :test is
___ or :key is ___. 

This doc is completely unclear to me.  I have no idea what it's trying
to say.  And the doc strings of these functions and macros don't help at
all with this.

If I look up the doc for, say `cl-incf' in the CL manual, it doesn't
help.  It says nothing about a non-variable PLACE (and nothing specific
about a variable PLACE, for that matter).  It just shows an example.

The manual entry for `cl-pushnew' is even worse.  It talks only about
`eql' and doesn't say anything about :test.  There's an xref to node
`Lists as Sets' for info about the keyword args, but that node also says
nothing about :test.  Instead, that node just punts further, to node
`Sequences'.

In general, this doc in this manual, and the CL doc strings, are nearly
useless, and perhaps harmful/misleading.  Certainly not very helpful.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''