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

[Drew Adams]

> > These are motion functions, just like `goto-char' and
> > `skip-chars-forward'.  Their doc should specify the return value
> > (regardless of whether it is a position, a Boolean, always nil, or
> > anything else).
> >
> > If, for some special (good) reason, 

What is that special, good reason?

> > code should not rely on the return value of some function then
> > this fact should be stated explicitly in the doc: "This function
> > is used only for its side effects; the return value is undefined."
> > This is Lisp, not C - return values are the norm,
> > not the exception.
> 
> No, in Emacs we seldom say that.  Functions used for side effect are
> quite normal.

Please _read_.  No one said that side-effect functions are abnormal.

These are NOT side-effect functions.  They modify nothing except
the cursor position.  These are normal, ordinary, run-of-the-mill
motion functions.  Their return values should be specified.  We
do not proscribe users from using the return value of motion
functions, in general - quite the contrary.

> > The doc of `(forward|backward)-(word|line)' already correctly
> > specifies the return value.  Not so for other
> > `(forward|backward)-*' functions, such as `(forward|backward)-sexp'.
> 
> They don't seem to return anything useful.  Closing.

Where do you get off saying that?  Of course it is useful to
use the return value of a motion function.  It saves a call to
`point', which can simplify the code.  (Yes, simple and beautiful
is in the eye of the reader.  But the point is that it is normal
for users to make use of the return value of a motion function
that is side-effect free.  Reopening.