GameModifiers: use descriptive parameter names + reformat + DOCUMENTgamemodifiers_clarity2

+ shift one argument's position in changeMode(...)

2 files changed, 71 insertions, 42 deletions

diff --git a/src/gamemodifiers.cpp b/src/gamemodifiers.cpp
index 5aa73f97a..89afe47e9 100644
--- a/src/gamemodifiers.cpp
+++ b/src/gamemodifiers.cpp
@@ -54,9 +54,9 @@
     const char *const GameModifiers::m##typeName##Strings[] = __VA_ARGS__; \
     std::string GameModifiers::get##typeName##String() \
     { \
-        return gettext(getVarItem(&m##typeName##Strings[0], \
-                                  CAST_U32(settings.varName), \
-                                  m##typeName##Size)); \
+        return gettext(getHumanString(&m##typeName##Strings[0], \
+                                      CAST_U32(settings.varName), \
+                                      m##typeName##Size)); \
     }
 
 #define addModifier2(typeName, varName, str, size, ...) \
@@ -64,21 +64,21 @@
     const char *const GameModifiers::m##typeName##Strings[] = __VA_ARGS__; \
     void GameModifiers::change##typeName(const bool forward) \
     { \
-        changeMode(&settings.varName, m##typeName##Size, str, \
-                   &GameModifiers::get##typeName##String, 0, true, forward); \
+        changeMode(&settings.varName, 0, m##typeName##Size, str, \
+                   &GameModifiers::get##typeName##String, true, forward); \
     } \
     std::string GameModifiers::get##typeName##String() \
     { \
-        return gettext(getVarItem(&m##typeName##Strings[0], \
-                                  settings.varName, \
-                                  m##typeName##Size)); \
+        return gettext(getHumanString(&m##typeName##Strings[0], \
+                                      settings.varName, \
+                                      m##typeName##Size)); \
     }
 
 #define changeMethod(typeName, varName, str) \
     void GameModifiers::change##typeName(const bool forward) \
     { \
-        changeMode(&settings.varName, m##typeName##Size, str, \
-                   &GameModifiers::get##typeName##String, 0, true, forward); \
+        changeMode(&settings.varName, 0, m##typeName##Size, str, \
+                   &GameModifiers::get##typeName##String, true, forward); \
     }
 
 void GameModifiers::init()
@@ -94,18 +94,18 @@ void GameModifiers::init()
     settings.magicAttackType = config.getIntValue("magicAttackType");
     settings.pvpAttackType = config.getIntValue("pvpAttackType");
     settings.imitationMode = config.getIntValue("imitationMode");
-    settings.disableGameModifiers = config.getBoolValue(
-        "disableGameModifiers");
+    settings.disableGameModifiers =
+        config.getBoolValue("disableGameModifiers");
     settings.awayMode = false;
     settings.mapDrawType = MapType::NORMAL;
 //    UpdateStatusListener::distributeEvent();
 }
 
 void GameModifiers::changeMode(unsigned *restrict const var,
+                               const unsigned first,
                                const unsigned limit,
-                               const char *restrict const conf,
-                               std::string (*const func)(),
-                               const unsigned def,
+                               const char *restrict const configKey,
+                               std::string (*const toHumanString)(),
                                const bool save,
                                const bool forward)
 {
@@ -116,7 +116,7 @@ void GameModifiers::changeMode(unsigned *restrict const var,
     {
         (*var) ++;
         if (*var >= limit)
-            *var = def;
+            *var = first;
     }
     else
     {
@@ -127,21 +127,23 @@ void GameModifiers::changeMode(unsigned *restrict const var,
     }
 
     if (save)
-        config.setValue(conf, *var);
+        config.setValue(configKey, *var);
     UpdateStatusListener::distributeEvent();
     GameModifierListener::distributeEvent();
-    const std::string str = (*func)();
+    // Announce new setting to user's chat.
+    const std::string str = (*toHumanString)();
     if (str.size() > 4)
         debugMsg(str.substr(4))
 }
 
-const char *GameModifiers::getVarItem(const char *const *const arr,
-                                      const unsigned index,
-                                      const unsigned sz)
+const char *GameModifiers::getHumanString(const char *const *const lut,
+                                          const unsigned index,
+                                          const unsigned size)
 {
-    if (index < sz)
-        return arr[index];
-    return arr[sz];
+    if (index < size)
+        return lut[index];
+    else
+        return lut[size];
 }
 
 addModifier(MoveType, moveType, 5,
@@ -163,8 +165,8 @@ addModifier(MoveType, moveType, 5,
 void GameModifiers::changeMoveType(const bool forward)
 {
     localPlayer->setMoveState(0);
-    changeMode(&settings.moveType, mMoveTypeSize, "invertMoveDirection",
-        &GameModifiers::getMoveTypeString, 0, false, forward);
+    changeMode(&settings.moveType, 0, mMoveTypeSize, "invertMoveDirection",
+               &GameModifiers::getMoveTypeString, false, forward);
 }
 
 const unsigned GameModifiers::mCrazyMoveTypeSize = 11;
@@ -172,8 +174,8 @@ const unsigned GameModifiers::mCrazyMoveTypeSize = 11;
 void GameModifiers::changeCrazyMoveType(const bool forward)
 {
     settings.crazyMoveState = 0U;
-    changeMode(&settings.crazyMoveType, mCrazyMoveTypeSize, "crazyMoveType",
-        &GameModifiers::getCrazyMoveTypeString, 1, true, forward);
+    changeMode(&settings.crazyMoveType, 1, mCrazyMoveTypeSize, "crazyMoveType",
+               &GameModifiers::getCrazyMoveTypeString, true, forward);
 }
 
 std::string GameModifiers::getCrazyMoveTypeString()
@@ -183,7 +185,7 @@ std::string GameModifiers::getCrazyMoveTypeString()
     {
         // TRANSLATORS: crazy move type in status bar
         return strprintf(_("(%u) crazy move number %u"),
-            crazyMoveType, crazyMoveType);
+                         crazyMoveType, crazyMoveType);
     }
     else if (crazyMoveType == mCrazyMoveTypeSize - 1)
     {
@@ -289,11 +291,10 @@ std::string GameModifiers::getQuickDropCounterString()
 {
     const unsigned int cnt = settings.quickDropCounter;
     if (cnt > 9)
-    {
-        return strprintf("(%c) drop counter %u", CAST_S8(
-            'a' + cnt - 10), cnt);
-    }
-    return strprintf("(%u) drop counter %u", cnt, cnt);
+        return strprintf("(%c) drop counter %u",
+                         CAST_S8('a' + cnt - 10), cnt);
+    else
+        return strprintf("(%u) drop counter %u", cnt, cnt);
 }
 
 void GameModifiers::setQuickDropCounter(const int n)
@@ -510,8 +511,8 @@ void GameModifiers::resetModifiers()
             map->setDrawLayersFlags(MapType::NORMAL);
     }
     settings.imitationMode = config.resetIntValue("imitationMode");
-    settings.disableGameModifiers = config.resetBoolValue(
-        "disableGameModifiers");
+    settings.disableGameModifiers =
+        config.resetBoolValue("disableGameModifiers");
 
     UpdateStatusListener::distributeEvent();
     GameModifierListener::distributeEvent();
diff --git a/src/gamemodifiers.h b/src/gamemodifiers.h
index 768fac3f4..14b0fdaed 100644
--- a/src/gamemodifiers.h
+++ b/src/gamemodifiers.h
@@ -37,13 +37,30 @@ class GameModifiers final
     public:
         A_DELETE_COPY(GameModifiers)
 
+        /*
+         * Load most modifiers from config.
+         */
         static void init();
 
+        /*
+         * Cycle through available modifier settings
+         *
+         * Assumes that settings start at 0 and end at limit-1 without holes.
+         *
+         * @param var        the variable that stores the current settings
+         * @param first      first valid setting (used when limit is reached)
+         * @param limit      how many settings there are (for looping around)
+         * @param configKey  name of this setting in config
+         * @param func       obtain human readable representation of the next setting
+         *                   used to print new setting state into debug log.
+         * @param save       toggles whether to save changed setting
+         * @param forward    direction of cycling
+        */
         static void changeMode(unsigned *restrict const var,
+                               const unsigned first,
                                const unsigned limit,
-                               const char *restrict const conf,
+                               const char *restrict const configKey,
                                std::string (*const func)(),
-                               const unsigned def,
                                const bool save,
                                const bool forward);
 
@@ -66,13 +83,24 @@ class GameModifiers final
 
         static void setQuickDropCounter(const int n);
 
+        /*
+         * Reset modifiers to their default values
+         */
         static void resetModifiers();
 
     protected:
-        static const char *getVarItem(const char *const *const arr,
-                                      const unsigned index,
-                                      const unsigned sz)
-                                      A_WARN_UNUSED A_NONNULL(1);
+        /*
+         * Return untranslated human representation of a setting's state
+         *
+         * @param     lut    look up table with strings before translation
+         * @param     index  setting's value
+         * @param     size   upper limit on setting's value (index of top
+         *                   element reserved for unknown/error string)
+         */
+        static const char *getHumanString(const char *const *const lut,
+                                       const unsigned index,
+                                       const unsigned size)
+                                       A_WARN_UNUSED A_NONNULL(1);
 };
 
 #undef declModifier