shithub: puzzles

Info  •  Files  •  Log  •  Branches

Add missing documentation of 'int dir' parameters.

This integer parameter appears in all of the game's anim_length,
flash_length and redraw methods, but the documentation only described
it properly in the section for anim_length.

The section for flash_length refers you to anim_length for the
description of all the parameters, but unhelpfully, it did so without
a conveniently clickable (in HTML) cross-reference.

And the section for game_redraw missed out the description of 'int
dir' completely, which is particularly unhelpful since that's the
function most likely to actually need to care about it! (Even if
forward and reversed move animations look different, they _probably_
still have the same duration, so it's more likely that anim_length
would ignore 'dir' and redraw would use it than vice versa.)

--- a/devel.but

+++ b/devel.but

@@ -1275,7 +1275,7 @@

 final locking move.

 The input parameters to \cw{flash_length()} are exactly the same as

-the ones to \cw{anim_length()}.

+the ones to \cw{anim_length()}: see \k{backend-anim-length}.

 Just like \cw{anim_length()}, when this function is called, it may

 rely on \cw{changed_state()} having been called previously, so if it

@@ -1391,6 +1391,14 @@

 that the animation has already been running. If \c{oldstate} is

 \cw{NULL}, then \c{anim_time} is unused (and will hopefully be set

 to zero to avoid confusion).

+

+\c{dir} specifies the chronological order of those states: if it is

+positive, then the transition is the result of a move or a redo (and

+so \c{newstate} is the later of the two moves), whereas if it is

+negative then the transition is the result of an undo (so that

+\c{newstate} is the \e{earlier} move). This allows move animations

+that are not time-symmetric (such as Inertia, where gems are consumed

+during the animation) to be drawn the right way round.

 \c{flash_time}, if it is is non-zero, denotes that the game is in

 the middle of a flash, and gives the time since the start of the