bug#62027: Subject: 29.0.60; Breaking change in forward-sentence/backward-sentence

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

> > > > Should perhaps the return values of
> > > > `forward-sentence'/`backward-sentence' be documented
> > > > to prevent this from happening again?
> > >
> > > Why not: Hyrum's law might have won here.  But OTOH in master,
> > > 'forward-sentence' is a now call to 'forward-sentence-function' that
> > > could be changed by the user.  Maybe should we document
> > > 'forward-sentence-default-function'?
> >
> > Yes, but _both_ should mention the return value.
> > And not just "to prevent this from happening again."
> > Documenting this helps users use the functions.
> 
> Not when the value is a simple consequence
> of the implementation, no.

Are you suggesting that to discover that
the position is returned users need to check
the implementation to see what's returned?

There are plenty of movement functions that
don't return point, even though it's not
obvious that their implementation wouldn't
return point.

How would you guess that `next-line' doesn't
return point, without checking its
implementation?  It seems to go out of its
way to return nil (not point), but it's not
obvious (to me) why that is.

More typically we return nil when a non-nil
value indicates something particular - but
not here.  Or we do so when we specifically,
i.e., for some reason, don't want users to
depend on any particular return value.

Not to mention that to know whether returning
point is "a simple consequence of the
implementation" isn't possible for a command
implemented in C, unless you happen to have
the C source code.

> forward-sentence does its job by side effect,
> not by the value it returns.

If you define "its job" that narrowly, yes.

But then why does it return (point)?  A (happy)
accident/coincidence or design/intended?

In any case, even if you define its job as only
moving, and not also as returning point, that
doesn't prevent it being useful that it returns
the position value.  It's useful to allow/use
code such as this:

(act-on-region some-position
               (forward-sentence N))

rather than

(act-on-region some-position
               (progn (forward-sentence N)
                      (point)))

For setq you could define "its job" as just
changing variable values.  But we return the
value.  Why do we?  Because that's useful.

I don't know why Emacs wouldn't want to let
users know about the useful return value of
a function such as `forward-sentence'.

(By "let users know" I mean help commands,
not just by providing the source code.)

And yes, it wouldn't hurt if _more_ motion
functions (including commands) returned
point. Some do (e.g. `move-beginning-of-line').
Some don't (e.g. `end-of-line', `forward-char').
Probably most don't.

And yes, of course there are motion functions
(e.g. `forward-line') that return a value
other than point - a value that's otherwise
useful.

The point isn't that motion functions should
always return point.  The point is that unless
there's a good reason not to return a useful
value, it's helpful to return a useful value -
and for movement, point can be useful to return.