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

[Dmitry Gutov <dgutov@yandex.ru>]

Drew Adams <drew.adams@oracle.com> writes:

> Everything in the universe has side effects.  Ohhmmmm.  It's true.

You should look up "referential transparency".

> Motion functions are not what is typically meant by a side-effect
> function.  They do not change the contents of the buffer, for
> example, in the sense of `buffer-modified-p'.

Please read http://en.wikipedia.org/wiki/Side_effect_(computer_science)

"function with side effects" is a pretty well-defined term. A function
does not necessarily have to modify an Emacs buffer to be termed as
such.

> By your (newfound) logic, you will presumably remove mention of
> the return value from the doc for those functions.  The same
> logic behind documenting their return value applies to these
> other motion functions.

The logic is simple: if the return value is documented, the caller
should be able to depend on it, and "undocumenting" it retroactively
isn't an option. As long as the return value is undocumented, but the
function can still be useful without it, it can stay that way
indefinitely.