bug#15117: 24.3.50; doc of `(forward|backward)-*': state return value

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

> > Everything in the universe has side effects.  Ohhmmmm.  It's true.
> 
> You should look up "referential transparency".

Perhaps you should give me the benefit of the doubt.  I'm actually
well aware of referential transparency.  That might even have been
the case before you uttered your first side-effect cry. ;-)

> Please read
> http://en.wikipedia.org/wiki/Side_effect_(computer_science)

Please spare me the comp-sci lesson.  FYI, I was at the Santa Fe
graph-reduction workshop in 1986, discussing what would ultimately
become Haskell with John Hughes, Phil Wadler, Paul Hudak, and Simon
Peyton-Jones.  That's only to assure you that I am somewhat at home
in this forest.

I've been a proponent of purely functional and logic programming
for over 30 years.  And yet I have also enjoyed programming in
nasty old Lisp for the same period. ;-)  Go figure.

> "function with side effects" is a pretty well-defined term. A
> function does not necessarily have to modify an Emacs buffer to
> be termed as such.

Cough, gag.  Yes, indeed.  I really did not mean to suggest
otherwise.

> > By your (newfound) logic, you will presumably remove mention of
> > the return value from the doc for those functions.  The same
> > logic behind documenting their return value applies to these
> > other motion functions.
> 
> The logic is simple: 

So are you arguing that we should not document the return value
of those functions either?  Meme combat.

> if the return value is documented, the caller should be able to
> depend on it, 

Yes, that's the idea.

> and "undocumenting" it retroactively isn't an option.  As long as
> the return value is undocumented, but the function can still be
> useful without it, it can stay that way indefinitely.

When have you ever seen Emacs Dev worry a lot about changing
something, let alone undocumenting a return value retroactively?
Let's not exaggerate.

Yes, the return value for these simple motion functions should be
documented, and thus users should be able to depend on it.

That is no more of a constraint on Emacs-Lisp implementors than
is letting users depend on the value of `point' when the function
is finished.

We are not designing a language standard that will be implemented
here and there around the world using different teams and different
technologies for different purposes for the next 100 years.

This is Emacs Lisp, not Common Lisp.  Let's not get carried away.
And even Common Lisp defines return values for the vast majority
of its functions, whether or not they perform side effects.