From e349f882e7b268b2feb9da59c387bc8afa323a54 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Fri, 27 Jan 2017 10:27:47 +0100 Subject: [PATCH] hooks: Add some documentation about the various hook functions Signed-off-by: Gergely Nagy --- src/hooks.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/hooks.h b/src/hooks.h index 99f1dd9e..686cd207 100644 --- a/src/hooks.h +++ b/src/hooks.h @@ -8,6 +8,24 @@ typedef Key (*custom_handler_t)(Key mappedKey, byte row, byte col, uint8_t keyState); extern custom_handler_t eventHandlers[HOOK_MAX]; +/* + * In most cases, one only wants a single copy of a hook. On the other hand, + * plugins that depend on other plugins, may want to make it easier for the + * end-user to use the plugin, and call the setup function of the dependent + * plugins too. In case the end-user calls the same setup function, we'd end up + * with hooks registered multiple times. + * + * To avoid this, protection against double-registration has been introduced. + * The `event_handler_hook_use` and `loop_hook_use` functions will only allow + * one copy of the hook. The `event_handler_hook_append` and `loop_hook_append` + * functions will, on the other hand, just append the hooks, and not care about + * protection. + * + * The `event_handler_hook_add` and `loop_hook_add` functions are deprecated, + * but for the time being, they are aliases to the `_use` functions, until all + * plugins have been updated, and the aliases can be removed. + */ + void event_handler_hook_use (custom_handler_t hook); void event_handler_hook_append (custom_handler_t hook); void event_handler_hook_replace (custom_handler_t oldHook, custom_handler_t newHook);