[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#20587: 24.1 forward-line docs inconsistent/surprising return value
From: |
Vivek Dasmohapatra |
Subject: |
bug#20587: 24.1 forward-line docs inconsistent/surprising return value |
Date: |
Sat, 23 May 2015 03:50:10 +0100 (BST) |
User-agent: |
Alpine 2.02 (DEB 1266 2009-07-14) |
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).
bug#20587: 24.1 forward-line docs inconsistent/surprising return value, Eric Hanchrow, 2015/05/22