Add javadocs to cheat-related functions

Author: kubaau

libs/s25main/CheatCommandTracker.h

@@ -15,12 +15,41 @@ class CheatCommandTracker
 public:
     CheatCommandTracker(Cheats& cheats);
 
+    /** Tracks keyboard events related to cheats and triggers the actual cheats.
+     * Calls related private methods of this class in order but returns at the first success (return true).
+     *
+     * @param ke - The keyboard event encountered.
+     */
     void trackKeyEvent(const KeyEvent& ke);
+
+    /** Tracks chat commands related to cheats and triggers the actual cheats.
+     *
+     * @param cmd - The chat command to track.
+     */
     void trackChatCommand(const std::string& cmd);
 
 private:
+    /** Tracks keyboard events related to cheats and triggers the actual cheats, but only tracks events of type
+     * different than KeyType::Char (e.g. F-keys).
+     *
+     * @param ke - The keyboard event encountered.
+     * @return true if keyboard event was NOT of type KeyType::Char, false otherwise
+     */
     bool trackSpecialKeyEvent(const KeyEvent& ke);
+
+    /** Tracks keyboard events related to game speed cheats (ALT+1..ALT+6) and triggers the actual cheats.
+     *
+     * @param ke - The keyboard event encountered.
+     * @return true if keyboard event was related to game speed cheats, false otherwise
+     */
     bool trackSpeedKeyEvent(const KeyEvent& ke);
+
+    /** Tracks keyboard events related to cheats and triggers the actual cheats, but only tracks events of type
+     * KeyType::Char (e.g. enabling cheat mode by typing "winter").
+     *
+     * @param ke - The keyboard event encountered.
+     * @return always true
+     */
     bool trackCharKeyEvent(const KeyEvent& ke);
 
     Cheats& cheats_;

libs/s25main/Cheats.h

@@ -20,22 +20,71 @@ class Cheats
     Cheats(GameWorldBase& world);
     ~Cheats(); // = default - for unique_ptr
 
+    /** In single player games, tracks keyboard events related to cheats.
+     * Delegates this responsibility to CheatCommandTracker, which triggers the actual cheats.
+     * In multiplayer games, does nothing. No cheats can be triggered in multiplayer.
+     *
+     * @param ke - The keyboard event encountered.
+     */
     void trackKeyEvent(const KeyEvent& ke);
+
+    /** In single player games, tracks chat commands related to cheats.
+     * Delegates this responsibility to CheatCommandTracker, which triggers the actual cheats.
+     * In multiplayer games, does nothing. No cheats can be triggered in multiplayer.
+     *
+     * @param cmd - The chat command to track.
+     */
     void trackChatCommand(const std::string& cmd);
 
+    /** Toggles cheat mode on and off.
+     * Cheat mode needs to be on for any cheats to trigger.
+     */
     void toggleCheatMode();
+    /** Used by clients to check if cheat mode is on (e.g. to draw special sprites or enable or all buildings).
+     * Cheat mode needs to be on for any cheats to trigger.
+     *
+     * @return true if cheat mode is on, false otherwise
+     */
     bool isCheatModeOn() const { return isCheatModeOn_; }
 
     // Classic S2 cheats
+
+    /** The classic F7 cheat.
+     * Does not modify game state, merely tricks clients into revealing the whole map.
+     * In the background, visibility is tracked as expected, i.e. if you reveal the map, send a scout and unreveal the
+     * map, you will see what was scouted.
+     */
     void toggleAllVisible();
     bool isAllVisible() const { return isAllVisible_; }
 
+    /** The classic build headquarters cheat.
+     * This function is used to check if the cheat building can be placed at the chosen point when opening the activity
+     * window.
+     *
+     * @param mp - The map point where the user clicked to open the activity window.
+     * @return true if the building can be placed, false otherwise
+     */
     bool canPlaceCheatBuilding(const MapPoint& mp) const;
+    /** The classic build headquarters cheat.
+     * This function is used to place the cheat building at the chosen point.
+     * The building is immediately fully built, there is no need for a building site.
+     *
+     * @param mp - The map point at which to place the building.
+     * @param player - The player to whom the building should belong.
+     */
     void placeCheatBuilding(const MapPoint& mp, const GamePlayer& player);
 
+    /** The classic ALT+1 through ALT+6 cheat which changes the game speed.
+     *
+     * @param speedIndex - 0 is normal, 1 is faster, 2 is even faster, etc.
+     */
     void setGameSpeed(uint8_t speedIndex);
 
     // RTTR cheats
+
+    /** Shares control of the (human) user's country with the AI. Both the user and the AI retain full control of the
+     * country, so the user can observe what the AI does or "cooperate" with it.
+     */
     void toggleHumanAIPlayer();
 
     void armageddon();
@@ -47,14 +96,30 @@ class Cheats
         Fish,
         Water
     };
+    /** Tells clients which resources to reveal:
+     * Nothing - reveal nothing
+     * Ores - reveal ores
+     * Fish - reveal ores and fish
+     * Water - reveal ores, fish and water
+     */
     ResourceRevealMode getResourceRevealMode() const;
     void toggleResourceRevealMode();
 
     using PlayerIDSet = std::unordered_set<unsigned>;
+    /** Destroys all buildings of given players, effectively defeating them.
+     *
+     * @param playerIds - Set of IDs of players.
+     */
     void destroyBuildings(const PlayerIDSet& playerIds);
+    /** Destroys all buildings of AI players.
+     */
     void destroyAllAIBuildings();
 
 private:
+    /** Checks if cheats can be turned on at all.
+     *
+     * @return true if if cheats can be turned on, false otherwise
+     */
     bool canCheatModeBeOn() const;
 
     std::unique_ptr<CheatCommandTracker> cheatCmdTracker_;

libs/s25main/world/GameWorldBase.h

@@ -96,7 +96,14 @@ class GameWorldBase : public World
     bool IsOnRoad(const MapPoint& pt) const;
     /// Check if a flag is at a neighbour node
     bool IsFlagAround(const MapPoint& pt) const;
+
+    /** Checks if any of the neighboring nodes of a given map point are owned by any player.
+     *
+     * @param pt - The map point whose neighbors should be checked.
+     * @return true if any neighbor has an owner, false otherwise
+     */
     bool IsAnyNeighborOwned(const MapPoint& pt) const;
+
     /// Berechnet BQ bei einer gebauten Stra�e
     void RecalcBQForRoad(MapPoint pt);
     /// Pr�ft, ob sich in unmittelbarer N�he (im Radius von 4) Milit�rgeb�ude befinden