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

[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.

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.