shithub: puzzles

Info  •  Files  •  Log  •  Branches

Explicitly document that various function pointers can be NULL

There are various functions pointed to by the game structure that are
only called if certain flags are set.  Some of them were documented as
not being called when the flags were clear, but there was no explicit
statement that the pointers could simply be NULL in that case.  Now
there is.

--- a/devel.but

+++ b/devel.but

@@ -661,7 +661,7 @@

 \c{game_params} structure.

 If the game's \c{can_configure} flag is set to \cw{false}, this

-function is never called and need not do anything at all.

+function is never called and can be \cw{NULL}.

 \S{backend-custom-params} \cw{custom_params()}

@@ -686,7 +686,7 @@

 the dialog box will stay open.)

 If the game's \c{can_configure} flag is set to \cw{false}, this

-function is never called and need not do anything at all.

+function is never called and can be \cw{NULL}.

 \S{backend-validate-params} \cw{validate_params()}

@@ -1089,7 +1089,8 @@

 \c                const char *aux, const char **error);

 This function is called when the user selects the \q{Solve} option

-from the menu.

+from the menu.  If \cw{can_solve} is \cw{false} then it will never

+be called and can be \cw{NULL}.

 It is passed two input game states: \c{orig} is the game state from

 the very start of the puzzle, and \c{curr} is the current one.

@@ -1471,7 +1472,7 @@

 make sense to print.)

 If this flag is \cw{false}, then the functions \cw{print_size()}

-and \cw{print()} will never be called.

+and \cw{print()} will never be called and can be \cw{NULL}.

 \S{backend-can-print-in-colour} \c{can_print_in_colour}

@@ -1569,7 +1570,8 @@

 If this field is \cw{false}, the functions

 \cw{can_format_as_text_now()} (\k{backend-can-format-as-text-now})

-and \cw{text_format()} (\k{backend-text-format}) are never called.

+and \cw{text_format()} (\k{backend-text-format}) are never called

+and can be \cw{NULL}.

 \S{backend-can-format-as-text-now} \c{can_format_as_text_now()}

@@ -1638,7 +1640,7 @@

 so, the mid-end will maintain a game timer while the user plays.

 If this field is \cw{false}, then \cw{timing_state()} will never be

-called and need not do anything.

+called and can be \cw{NULL}.

 \S{backend-timing-state} \cw{timing_state()}