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

[Andreas Röhler]

Am 11.02.2014 18:29, schrieb Drew Adams:
> > If you (Drew) want that something productive comes out of this,
> > please point out specific forward/backward-* functions that return
> > non-trivial values, and those values are not documented.  The only 2
> > functions mentioned since the beginning of this discussion are
> > forward/backward-sexp, which always return nil, a.k.a. "nothing".  I
> > also tried a couple of other random functions, and they seem all to
> > be of this "nothing" kind.  So I wonder whether we have any real
> > problem here.
>
> I would like to see functions that are purely motion functions
> return `point', the destination position, unless there is a more
> useful return value (as is already the case for a function such as
> `forward-comment' or `forward-button').
>
> IOW, some useful value is better than none.  Note: I have nothing
> against picking a _more_ useful value than `point'.  Point is just
> a default suggestion.  For an example of a more useful value, see
> `forward-comment': it sets `point' but returns t or nil.

IMO these functions should return point if successful, i.e. if point was moved, 
but nil otherwise, for example at EOB.
As point --a number-- evals to `t', a respective check might be set upon from 
receiving function.

> And document that return value.  Here are some candidates, for a
> start (likewise, their backward relatives, and other relatives,
> such as `up-list', `down-list', `backward-up-list'...).
>
> forward-char
> forward-list ; already returns `point'
> forward-page ; returns count
> forward-same-syntax
> forward-sentence
> forward-sexp
> forward-symbol
> forward-thing
> forward-to-indentation
> forward-visible-line
> forward-whitespace
> forward-word
>
> We can look for other motion functions to treat similarly after
> this start.  Assuming there is any will to do this.