Move deprecation messages to a separate header

Moving the deprecation messages to a separate header, and adding a few helpers
allow us to write much more detailed deprecation messages, without needlessly
making the code look incredibly messy.

This also updates most of the deprecation messages to be much more helpful, and
provide hints at how to fix the warnings produced by them.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>

src/Kaleidoscope.h

@@ -26,6 +26,7 @@ void setup();
 #include "layers.h"
 #include "macro_map.h"
 #include "kaleidoscope_internal/event_dispatch.h"
+#include "kaleidoscope_internal/deprecations.h"
 #include "macro_helpers.h"
 #include "plugin.h"
 
@@ -67,8 +68,7 @@ static_assert(KALEIDOSCOPE_REQUIRED_API_VERSION == KALEIDOSCOPE_API_VERSION,
               " available, but version " xstr(KALEIDOSCOPE_REQUIRED_API_VERSION) " is required.");
 #endif
 
-const uint8_t KEYMAP_SIZE
+const uint8_t KEYMAP_SIZE DEPRECATED(KEYMAP_SIZE) = 0;
-__attribute__((deprecated("Kaleidoscope.setup() does not require KEYMAP_SIZE anymore."))) = 0;
 
 namespace kaleidoscope {
 
@@ -76,8 +76,7 @@ class Kaleidoscope_ {
  public:
   Kaleidoscope_(void);
 
-  void setup(const byte keymap_count)
+  void setup(const byte keymap_count) DEPRECATED(KEYMAP_SIZE) {
-  __attribute__((deprecated("The keymap_count argument (and the KEYMAP_SIZE macro) are unused, and can be safely removed."))) {
     setup();
   }
   void setup(void);
@@ -86,38 +85,13 @@ class Kaleidoscope_ {
   // ---- Kaleidoscope.use() ----
 
 #if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
-#define DEPRECATED_USE "\n"                                                         \
-    "------------------------------------------------------------------------\n"    \
-    "Your sketch uses Kaleidoscope.use(), an old-style API to initialize\n"         \
-    "plugins. To fix this, you need to modify your .ino sketch file, and\n"         \
-    "replacing the text \"Kaleidoscope.use\" with \"KALEIDOSCOPE_INIT_PLUGINS\",\n" \
-    "then remove the & from all of the plugins inside it, and finally, move\n"      \
-    "it outside of \"setup()\":\n"                                                  \
-    "\n"                                                                            \
-    "If your current sketch looks like this: \n"                                    \
-    "  void setup() {\n"                                                            \
-    "    Kaleidoscope.use(&Plugin1, &Plugin2);\n"                                   \
-    "    Kaleidoscope.setup();\n"                                                   \
-    "  }\n"                                                                         \
-    "\n"                                                                            \
-    "You should change it so that it looks like this:\n"                            \
-    "  KALEIDOSCOPE_INIT_PLUGINS(Plugin1, Plugin2);\n"                              \
-    "  void setup() {\n"                                                            \
-    "    Kaleidoscope.setup();\n"                                                   \
-    "  }\n"                                                                         \
-    "\n"                                                                            \
-    "If this error doesn't make sense to you or you have any trouble, please\n"     \
-    "send a copy of your .ino sketch file to help@keyboard.io and we can\n"         \
-    "help fix it.\n"                                                                \
-    "------------------------------------------------------------------------\n"
-
   // First, we have the zero-argument version, which will satisfy the tail case.
   inline void use() {
   }
 
   // Then, the one-argument version, that gives us type safety for a single
   // plugin.
-  inline void __attribute__((deprecated(DEPRECATED_USE))) use(kaleidoscope::Plugin *p) {
+  inline void DEPRECATED(USE) use(kaleidoscope::Plugin *p) {
     p->begin();
   }
 
@@ -132,7 +106,7 @@ class Kaleidoscope_ {
   // are passed back to either ourselves, or the zero-argument version a few
   // lines above.
   template <typename... Plugins>
-  void __attribute__((deprecated(DEPRECATED_USE))) use(kaleidoscope::Plugin *first, Plugins&&... plugins) {
+  void DEPRECATED(USE) use(kaleidoscope::Plugin *first, Plugins&&... plugins) {
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
     use(first);
@@ -160,21 +134,21 @@ class Kaleidoscope_ {
   static eventHandlerHook eventHandlers[HOOK_MAX];
 
   static void replaceEventHandlerHook(eventHandlerHook oldHook, eventHandlerHook newHook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.onKeyswitchEvent(...) instead.")));
+  DEPRECATED(EVENT_HANDLER_HOOK);
   static void appendEventHandlerHook(eventHandlerHook hook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.onKeyswitchEvent(...) instead.")));
+  DEPRECATED(EVENT_HANDLER_HOOK);
   static void useEventHandlerHook(eventHandlerHook hook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.onKeyswitchEvent(...) instead.")));
+  DEPRECATED(EVENT_HANDLER_HOOK);
 
   typedef void (*loopHook)(bool postClear);
   static loopHook loopHooks[HOOK_MAX];
 
   static void replaceLoopHook(loopHook oldHook, loopHook newHook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.beforeEachCycle(), .beforeReportingState(...) or .afterEachCycle(...) instead.")));
+  DEPRECATED(LOOP_HOOK);
   static void appendLoopHook(loopHook hook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.beforeEachCycle(), .beforeReportingState(...) or .afterEachCycle(...) instead.")));
+  DEPRECATED(LOOP_HOOK);
   static void useLoopHook(loopHook hook)
-  __attribute__((deprecated("Please implement kaleidoscope::Plugin.beforeEachCycle(), .beforeReportingState(...) or .afterEachCycle(...) instead.")));
+  DEPRECATED(LOOP_HOOK);
 
   static bool focusHook(const char *command);
 };
@@ -201,12 +175,11 @@ using kaleidoscope::Kaleidoscope;
 /* -- DEPRECATED aliases; remove them when there are no more users. -- */
 
 void event_handler_hook_use(kaleidoscope::Kaleidoscope_::eventHandlerHook hook)
-__attribute__((deprecated("Use Kaleidoscope.useEventHandlerHook instead")));
+DEPRECATED(EVENT_HANDLER_HOOK);
 void loop_hook_use(kaleidoscope::Kaleidoscope_::loopHook hook)
-__attribute__((deprecated("Use Kaleidoscope.useLoopHook instead")));
+DEPRECATED(LOOP_HOOK);
 
-void __USE_PLUGINS(kaleidoscope::Plugin *plugin, ...)
+void __USE_PLUGINS(kaleidoscope::Plugin *plugin, ...) DEPRECATED(USE);
-__attribute__((deprecated("Use Kaleidoscope.use(...) instead")));
 
 #define USE_PLUGINS(...) __USE_PLUGINS(__VA_ARGS__, NULL)
 

src/kaleidoscope_internal/deprecations.h

@@ -0,0 +1,63 @@
+#pragma once
+
+#define DEPRECATED(tag)                                                 \
+  __attribute__((deprecated(_DEPRECATE(_DEPRECATED_MESSAGE_ ## tag))))
+
+#define _DEPRECATE(message) "\n"                                               \
+  "------------------------------------------------------------------------\n" \
+  message                                                                      \
+  "\n"                                                                         \
+  "------------------------------------------------------------------------\n" \
+
+/* Messages */
+
+#define _DEPRECATED_MESSAGE_KEYMAP_SIZE                                    \
+  "Kaleidoscope.setup() does not require KEYMAP_SIZE anymore. It can be\n" \
+  "safely removed."
+
+#define _DEPRECATED_MESSAGE_USE                                                    \
+   "Your sketch uses Kaleidoscope.use(), an old-style API to initialize\n"         \
+   "plugins. To fix this, you need to modify your .ino sketch file, and\n"         \
+   "replacing the text \"Kaleidoscope.use\" with \"KALEIDOSCOPE_INIT_PLUGINS\",\n" \
+   "then remove the & from all of the plugins inside it, and finally, move\n"      \
+   "it outside of \"setup()\":\n"                                                  \
+   "\n"                                                                            \
+   "If your current sketch looks like this: \n"                                    \
+   "  void setup() {\n"                                                            \
+   "    Kaleidoscope.use(&Plugin1, &Plugin2);\n"                                   \
+   "    Kaleidoscope.setup();\n"                                                   \
+   "  }\n"                                                                         \
+   "\n"                                                                            \
+   "You should change it so that it looks like this:\n"                            \
+   "  KALEIDOSCOPE_INIT_PLUGINS(Plugin1, Plugin2);\n"                              \
+   "  void setup() {\n"                                                            \
+   "    Kaleidoscope.setup();\n"                                                   \
+   "  }\n"                                                                         \
+   "\n"                                                                            \
+   "If this error doesn't make sense to you or you have any trouble, please\n"     \
+   "send a copy of your .ino sketch file to help@keyboard.io and we can\n"         \
+   "help fix it."
+
+#define _DEPRECATED_MESSAGE_EVENT_HANDLER_HOOK                             \
+  "The legacy plugin API based on hook registration is deprecated.\n"      \
+  "\n"                                                                     \
+  "Consider upgrading your plugins, or implementing the new interface\n"   \
+  "described by `kaleidoscope::Plugin`. In particular, instead of using\n" \
+  "`Kaleidoscope.useEventHandlerHook`, implement the\n"                    \
+  "`.onKeyswitchEvent()` method instead."
+
+
+#define _DEPRECATED_MESSAGE_LOOP_HOOK                                      \
+  "The legacy plugin API based on hook registration is deprecated.\n"      \
+  "\n"                                                                     \
+  "Consider upgrading your plugins, or implementing the new interface\n"   \
+  "described by `kaleidoscope::Plugin`. In particular, instead of using\n" \
+  "`Kaleidoscope.useLoopHook`, implement `.beforeEachCycle`,\n"            \
+  "`.beforeReportingState()`, or `.afterEachCycle()` instead."
+
+#define _DEPRECATED_MESSAGE_USE_INSTEAD(new_method) \
+  "Please use `" new_method "` instead."
+
+#define _DEPRECATED_MESSAGE_KALEIDOSCOPEPLUGIN                                 \
+  "The `KaleidoscopePlugin` class is deprecated. Please derive plugins from\n" \
+  "`kaleidoscope::Plugin` instead."

src/key_defs_keymaps.h

@@ -1,6 +1,8 @@
 #pragma once
 
-static const uint8_t MOMENTARY_OFFSET __attribute__((deprecated)) = 42;
+#include "kaleidoscope_internal/deprecations.h"
+
+static const uint8_t MOMENTARY_OFFSET DEPRECATED(USE_INSTEAD("LAYER_SHIFT_OFFSET")) = 42;
 static const uint8_t LAYER_SHIFT_OFFSET = 42;
 
 #define KEYMAP_0     0

src/keyswitch_state.h

@@ -38,15 +38,15 @@
 
 // Deprecated - Remove once the core has transitioned
 
-inline uint8_t __attribute__((deprecated("Use keyWasPressed instead"))) key_was_pressed(uint8_t keyState) {
+inline uint8_t DEPRECATED(USE_INSTEAD("keyWasPressed")) key_was_pressed(uint8_t keyState) {
   return keyWasPressed(keyState);
 }
-inline uint8_t __attribute__((deprecated("Use keyIsPressed instead"))) key_is_pressed(uint8_t keyState) {
+inline uint8_t DEPRECATED(USE_INSTEAD("keyIsPressed")) key_is_pressed(uint8_t keyState) {
   return keyIsPressed(keyState);
 }
-inline uint8_t __attribute__((deprecated("Use keyToggledOn instead"))) key_toggled_on(uint8_t keyState) {
+inline uint8_t DEPRECATED(USE_INSTEAD("keyToggledOn")) key_toggled_on(uint8_t keyState) {
   return keyToggledOn(keyState);
 }
-inline uint8_t __attribute__((deprecated("Use keyToggledOff instead"))) key_toggled_off(uint8_t keyState) {
+inline uint8_t DEPRECATED(USE_INSTEAD("keyToggledOff")) key_toggled_off(uint8_t keyState) {
   return keyToggledOff(keyState);
 }

src/plugin.h

@@ -2,6 +2,7 @@
 
 #include "kaleidoscope/event_handler_result.h"
 #include "kaleidoscope_internal/event_dispatch.h"
+#include "kaleidoscope_internal/deprecations.h"
 #include "event_handlers.h"
 
 #ifndef KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
@@ -91,4 +92,4 @@ class Plugin : public EventHandlerBasePlugin {
 
 } // namespace kaleidoscope
 
-typedef kaleidoscope::Plugin KaleidoscopePlugin __attribute__((deprecated("class KaleidoscopePlugin is deprecated. Please derive plugins from kaleidoscope::Plugin instead.")));
+typedef kaleidoscope::Plugin KaleidoscopePlugin DEPRECATED(KALEIDOSCOPEPLUGIN);