bug#20587: 24.1 forward-line docs inconsistent/surprising return value

[Vivek Dasmohapatra]

In GNU Emacs 24.1.1 (x86_64-pc-linux-gnu, GTK+ Version 2.24.10)
 of 2012-08-23 on noise, modified by Debian

In the elisp manual, (forward-line X) is described as returning
the number of lines left to move if it cannot satisfy the caller's
request to move forward X lines.

However, calling (forward-line 1) at the start of a line with
no terminating newline (ie the incomplete final line in a buffer,
if it is incomplete) returns 0.

Calling (forward-line 1) at the _end_ of such a line returns 1.

The docstring for forward line does say the following at the end:

“With positive N, a non-empty line at the end counts as one line
 successfully moved (for the return value).”

I think this is surprising and inconsistent behaviour. It doesn't seem
reasonable to me, especially given that the documentation starts with:

“Move N lines forward (backward if N is negative).
 Precisely, if point is on line I, move to the start of line I + N
 ("start of line" in the logical order).”

In any case, even if forward-line is not altered (I suppose it is
possible that this behaviour has been around for a long time, and
many things may depend on forward-line behaving in this manner),
the Info manual should be updated to match the docstring.

I also think the surprising behaviour is not clearly flagged: It is
part of a single lump of docstring text, and not flagged or highlighted
in any way (a simple extra blank line before its description, or a
"NOTE:" or similar would make it much easier to spot).