Deprecate MACRODOWN preprocessor macro

Its utility is very limited now that `macroAction()` only gets called when a
Macros key toggles on or off, and it uses a symbol that breaks an abstraction
barrier (a local variable of the `macroAction()` function).

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

plugins/Kaleidoscope-Macros/README.md

@@ -37,11 +37,14 @@ M(MACRO_MODEL01), M(MACRO_HELLO), M(MACRO_SPECIAL)
 const macro_t *macroAction(uint8_t macro_id, KeyEvent &event) {
   switch (macro_id) {
   case MACRO_MODEL01:
-    return MACRODOWN(I(25),
-                     D(LeftShift), T(M), U(LeftShift), T(O), T(D), T(E), T(L),
-                     T(Spacebar),
-                     W(100),
-                     T(0), T(1) );
+    if (keyToggledOn(event.state)) {
+      return MACRO(I(25),
+                   D(LeftShift), T(M), U(LeftShift), T(O), T(D), T(E), T(L),
+                   T(Spacebar),
+                   W(100),
+                   T(0), T(1) );
+    }
+    break;
   case MACRO_HELLO:
     if (keyToggledOn(event.state)) {
       return Macros.type(PSTR("Hello "), PSTR("world!"));
@@ -128,8 +131,7 @@ The plugin provides a `Macros` object, with the following methods and properties
 
 Macros need to be able to simulate key down and key up events for any key - even
 keys that may not be on the keymap otherwise. For this reason and others, we
-need to define them in a special way, using the `MACRO` helper (or its
-`MACRODOWN()` variant, see below):
+need to define them in a special way, using the `MACRO` helper.
 
 ### `MACRO(steps...)`
 
@@ -141,20 +143,6 @@ need to define them in a special way, using the `MACRO` helper (or its
 > that end with END will still work correctly, but new code should not use END;
 > usage of END is deprecated.
 
-### `MACRODOWN(steps...)`
-
-> The same as the `MACRO()` helper above, but it will create a special sequence,
-> where the steps are only played back when the triggering key was just pressed.
-> That is, the macro will not be performed when the key is released, or held, or
-> not pressed at all.
->
-> Use this over `MACRO()` when you only want to perform an action when the key
-> actuates, and no action should be taken when it is held, released, or when it
-> is not pressed at all. For a lot of macros that emit a sequence without any
-> other side effects, `MACRODOWN()` is usually the better choice.
->
-> Can only be used from the `macroAction()` overrideable method.
-
 ## `MACRO` steps
 
 Macro steps can be divided into the following groups:

plugins/Kaleidoscope-Macros/src/kaleidoscope/plugin/Macros.cpp

@@ -33,6 +33,12 @@ __attribute__((weak))
 const macro_t *macroAction(uint8_t macro_id, uint8_t key_state) {
   return MACRO_NONE;
 }
+
+const macro_t* deprecatedMacroDown(uint8_t key_state, const macro_t* macro_p) {
+  if (keyToggledOn(key_state))
+    return macro_p;
+  return MACRO_NONE;
+}
 #pragma GCC diagnostic pop
 #endif
 

plugins/Kaleidoscope-Macros/src/kaleidoscope/plugin/Macros.h

@@ -60,6 +60,13 @@
   "uses a `KeyEvent` as its second parameter, giving access to the address\n"  __NL__ \
   "of the event in the `event.addr` member variable."
 
+#define _DEPRECATED_MESSAGE_MACROS_MACRODOWN                                   __NL__ \
+  "The `MACRODOWN()` preprocessor macro is deprecated. Please use `MACRO()`\n" __NL__ \
+  "with a test for `keyToggledOn(event.state)` instead."
+
+DEPRECATED(MACROS_MACRODOWN)
+const macro_t* deprecatedMacroDown(uint8_t key_state, const macro_t* macro_p);
+
 #endif
 
 // =============================================================================

plugins/Kaleidoscope-Macros/src/kaleidoscope/plugin/Macros/MacroSteps.h

@@ -52,7 +52,10 @@ typedef uint8_t macro_t;
       &__m[0];                                                          \
     })
 
-#define MACRODOWN(...) (keyToggledOn(keyState) ? MACRO(__VA_ARGS__) : MACRO_NONE)
+#ifndef NDEPRECATED
+#define MACRODOWN(...)                                  \
+  deprecatedMacroDown(event.state, MACRO(__VA_ARGS__));
+#endif
 
 #define I(n)  MACRO_ACTION_STEP_INTERVAL, n
 #define W(n)  MACRO_ACTION_STEP_WAIT, n