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

[Vivek Dasmohapatra <vivek@etla.org>]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1606 bytes --]

>  With positive N, a non-empty line at the end counts as one line
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  successfully moved (for the return value).
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> If those 2 sentences don't describe the situation with a buffer that
> ends in a line without a newline, then what is missing or unclear
> here, in your opinion?

What is unclear or misleading is, imo, the following:

  - The docstring begins by defining moving forward 1 line as
    moving to the start of the next line.

  - It then states that the function will return the number of lines
    left to move (compared to what the user requested)

  - It states that failing to move the requested number of lines is not
    an error.

So far, so good.

However, it then says, as a sparse footnote:

   “With positive N, a non-empty line at the end counts as one line”

So we have a problem of description:

“a non-empty line at the end counts as one line” is being used to mean
“a partial final line counts as a whole line”. I think this is obscure,
and its meaning is only evident in hindsight, having used the function
and discovered that forward-line returns its complete-success value (0)
even when it has not moved forward a line (per its own definition).

I also happen to think the behaviour is not sensible: If I ask to move 
forward 1 (complete) line and this canot be satisfied, the function
should return 1, as there is still 1 line left to move (but I acknowledge
that this is an old function and many things use it, and this may not
be a safe change).