try_scrolling question

try_scrolling question

[Po Lu]

What does the "value" in the comment on top of `try_scrolling' refer to?

   Try scrolling PT into view in window WINDOW.  JUST_THIS_ONE_P means
   only WINDOW is redisplayed in redisplay_internal.  TEMP_SCROLL_STEP
   has the same meaning as emacs_scroll_step, and is used in
   redisplay_window to bring a partially visible line into view in the
   case that only the cursor has moved.

   LAST_LINE_MISFIT should be true if we're scrolling because the last
   screen line's vertical height extends past the end of the screen.

   Value is
   ^^^^^

   1	if scrolling succeeded

   0	if scrolling didn't find point.

   -1 if new fonts have been loaded so that we must interrupt redisplay,
   adjust glyph matrices, and try again.

Does it mean the return value of try_scrolling?  If so, I don't
understand how 0 (SCROLLING_SUCCESS) is returned if it can't find point,
and how -1 can be returned at all.

Am I missing something here?

Thanks.

Re: try_scrolling question

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Date: Sat, 04 Dec 2021 15:38:49 +0800
> 
>    Value is
>    ^^^^^
> 
>    1	if scrolling succeeded
> 
>    0	if scrolling didn't find point.
> 
>    -1 if new fonts have been loaded so that we must interrupt redisplay,
>    adjust glyph matrices, and try again.
> 
> Does it mean the return value of try_scrolling?

Yes.  "Value is ..." is our style in documenting the return value of a
function.

> If so, I don't understand how 0 (SCROLLING_SUCCESS) is returned if
> it can't find point, and how -1 can be returned at all.

Heh, a classic case of comments not matching the code.  The code never
looks at the literal values though, only at enumeration values, so the
code works correctly.  I've now fixed the enumeration to match the
comment.  Thanks for catching this (very old) blunder.