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

[Eli Zaretskii]

> Date: Tue, 11 Feb 2014 09:29:24 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: lekktu@gmail.com, 15117@debbugs.gnu.org, larsi@gnus.org
> 
> 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').

That's a different issue: you are asking to change the functions
rather than to document what they currently do.  Let's stay with the
latter.

> 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

Returns nil, so I don't see what is there to document.

> forward-list ; already returns `point'
> forward-page ; returns count

Returns nil, not count.

> forward-same-syntax

Returns nil.

> forward-sentence
> forward-sexp

Returns nil.

> forward-symbol
> forward-thing

Always returns t, so not interesting.

> forward-to-indentation

The value is random, so not interesting

> forward-visible-line

Always nil.

> forward-whitespace
> forward-word

Value is documented.

Looks like only 4 functions of the list return something non-trivial.