Fix documentation of forward-line

* src/cmds.c (Fforward_line): Clarify the return value if the line
at end of accessible portion of the buffer has no newline.
* doc/lispref/positions.texi (Text Lines): Document what happens
if the line at end of accessible portion of buffer has no newline.

(Bug#20587)

1 files changed, 10 insertions, 3 deletions

diff --git a/src/cmds.c b/src/cmds.c
index b590805ea8a..6f9982eebb2 100644
--- a/src/cmds.c
+++ b/src/cmds.c
@@ -110,10 +110,17 @@ DEFUN ("forward-line", Fforward_line, Sforward_line, 0, 1, "^p",
 Precisely, if point is on line I, move to the start of line I + N
 \("start of line" in the logical order).
 If there isn't room, go as far as possible (no error).
+
 Returns the count of lines left to move.  If moving forward,
-that is N - number of lines moved; if backward, N + number moved.
-With positive N, a non-empty line at the end counts as one line
-successfully moved (for the return value).  */)
+that is N minus number of lines moved; if backward, N plus number
+moved.
+
+Exception: With positive N, a non-empty line at the end of the
+buffer, or of its accessible portion, counts as one line
+successfully moved (for the return value).  This means that the
+function will move point to the end of such a line and will count
+it as a line moved across, even though there is no next line to
+go to its beginning.  */)
   (Lisp_Object n)
 {
   ptrdiff_t opoint = PT, pos, pos_byte, shortage, count;