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

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''

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

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

This is modifying the statement before the table:

---
The following simple functions and macros are defined in @file{cl-lib.el};
they do not cause other components like @file{cl-extra} to be loaded.
---

> Similarly for the other names and their footnotes.

Same for them.

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

I've now removed the eql claim, and punted the explanation for :test to
"Lists as Sets".

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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.
> 
> This is modifying the statement before the table:
> 
> ---
> The following simple functions and macros are defined in
> @file{cl-lib.el}; they do not cause other components like
> @file{cl-extra} to be loaded.
> ---

Still not clear.  They are defined in cl-lib only when
PLACE is a var name?  They don't cause other components
to be loaded only when PLACE is a var name?

> > Similarly for the other names and their footnotes.
> 
> Same for them.

It's not clear to me whether you've fixed the doc or are
just trying to explain it to me.  If the latter then this
is, I guess, a "won't fix".  (It needs to be fixed.)

> > 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'.
> 
> I've now removed the eql claim, and punted the explanation for :test to
> "Lists as Sets".

Dunno what that means.  Does it mean that `Lists as Sets'
has been updated to cover the keyword args, including
:test?