Subject: RE: bug#28736: 24.5; doc of `push'

From: Drew Adams <[email-masked]>
Date: Sun, 8 Oct 2017 12:40:08 -0700 (PDT)

> > > > why is it a problem to document this?
> > >
> > > <Shrug> Because we don't want to guarantee the return
> > > value won't change in the future?
> >
> > Are you sure?
> 
> No.
> 
> > When was that decided?
> 
> I don't know if it was decided and when, I was just wondering
> whether the lack of documentation is deliberate or an omission.

Good.  Neither do I know that we don't want to guarantee
that the return value won't change.  Nor do I know whether
the lack of documentation was deliberate or not.  Nor do I
know a reason why we wouldn't want to document the behavior,
guarantee or no guarantee. 

Not having any reason to think there was a deliberate
decision not to document this, and not knowing any good
reason why it should not be documented, whether it was
deliberate or (a priori more likely) an oversight, and
knowing good reasons why it _should_ be documented (it
is useful, and documenting that use is the practice in
Lisp in general, and it fits what we do for things like
`setq'), this should be a no-brainer, IMO.

But if there is a good reason why it should not be
documented, let's hear it, please.