From e2f4463c3e3c24783bb777e932587e3c266e3297 Mon Sep 17 00:00:00 2001 From: Ben Harris Date: Tue, 31 Jan 2023 22:27:16 +0000 Subject: [PATCH] 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. --- devel.but | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/devel.but b/devel.but index 87df788..26371d3 100644 --- a/devel.but +++ b/devel.but @@ -661,7 +661,7 @@ the initial values of all the controls according to the input \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 @@ input \c{config_item} array. (If the parameters fail to validate, 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 @@ offer the \q{Solve} menu option. \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 @@ Twiddle, inherently involve moving things around and so would not 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 @@ just too difficult. 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 @@ This field is \cw{true} if the puzzle is time-critical. If 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()}