diff --git a/src/actions.cpp b/src/actions.cpp index 2f0c6fe58dc..d68ee34244b 100644 --- a/src/actions.cpp +++ b/src/actions.cpp @@ -12,8 +12,10 @@ See the COPYING file for more details. */ -//! @file actions.cpp -//! Recruiting, Fighting. +/** + * @file actions.cpp + * Recruiting, Fighting. + */ #include "actions.hpp" #include "attack_prediction.hpp" @@ -340,7 +342,7 @@ battle_context& battle_context::operator=(const battle_context &other) return *this; } -//! @todo FIXME: Hand previous defender unit in here. +/** @todo FIXME: Hand previous defender unit in here. */ int battle_context::choose_defender_weapon(const unit &attacker, const unit &defender, unsigned attacker_weapon, const gamemap& map, const std::vector& teams, const unit_map& units, const gamestatus& status, @@ -541,8 +543,7 @@ bool battle_context::better_combat(const combatant &us_a, const combatant &them_ return them_a.average_hp() < them_b.average_hp(); } -// Get the simulation results. -//! @todo FIXME: better to initialize combatant initially (move into unit_stats?), just do fight() when required. +/** @todo FIXME: better to initialize combatant initially (move into unit_stats?), just do fight() when required. */ const combatant &battle_context::get_attacker_combatant(const combatant *prev_def) { // We calculate this lazily, since AI doesn't always need it. @@ -604,7 +605,7 @@ battle_context::unit_stats::unit_stats(const unit &u, const gamemap::location& u weapon = &u.attacks()[attack_num]; } if(u.hitpoints() < 0) { - //! @todo FIXME enable after 1.3.2 and find out why this happens -- Mordante + /** @todo FIXME enable after 1.3.2 and find out why this happens -- Mordante */ // LOG_STREAM(err, config) << "Unit with " << u.hitpoints() << " hitpoints found, set to 0 for damage calculations\n"; hp = 0; } else if(u.hitpoints() > u.max_hitpoints()) { @@ -799,12 +800,14 @@ void attack::fire_event(const std::string& n) // defender, so we have to make sure they still exist a_ = units_.find(attacker_); d_ = units_.find(defender_); - //! @todo FIXME: If the event removes this attack, we should stop attacking. - // The previous code checked if 'attack_with' and 'defend_with' - // were still within the bounds of the attack arrays, - // or -1, but it was incorrect. - // The attack used could be removed and '*_with' variables - // could still be in bounds but point to a different attack. + /** + * @todo FIXME: If the event removes this attack, we should stop attacking. + * The previous code checked if 'attack_with' and 'defend_with' + * were still within the bounds of the attack arrays, + * or -1, but it was incorrect. + * The attack used could be removed and '*_with' variables + * could still be in bounds but point to a different attack. + */ if(a_ == units_.end() || d_ == units_.end()) { if (update_display_){ recalculate_fog(map_,units_,teams_,attacker_side-1); @@ -839,8 +842,6 @@ attack::~attack() delete bc_; } -//! Battle logic - attack::attack(game_display& gui, const gamemap& map, std::vector& teams, gamemap::location attacker, @@ -1655,7 +1656,7 @@ void calculate_healing(game_display& disp, const gamemap& map, healing = map.gives_healing(i->first); healers.clear(); } - //! @todo FIXME + /** @todo FIXME */ curing = "cured"; curer = units.end(); } @@ -1921,9 +1922,11 @@ namespace { return result; } - //! Returns true if some shroud is cleared. - //! seen_units will return new units that have been seen by this unit. - //! If known_units is NULL, seen_units can be NULL and will not be changed. + /** + * Returns true if some shroud is cleared. + * seen_units will return new units that have been seen by this unit. + * If known_units is NULL, seen_units can be NULL and will not be changed. + */ bool clear_shroud_unit(const gamemap& map, const unit_map& units, const gamemap::location& loc, std::vector& teams, int team, @@ -2128,10 +2131,12 @@ size_t move_unit(game_display* disp, // during a sighted event in clear_shroud_unit() ui = units.find(route.front()); if(ui == units.end()) { - //! @todo FIXME: the correct behavior for sighted event would be - // to halt movement, then fire "sighted" after firing "moveto" (see below). - // However, since we have fired "sighted" during movement calculations - // this is a workaround to prevent a crash. + /** + * @todo FIXME: the correct behavior for sighted event would be + * to halt movement, then fire "sighted" after firing "moveto" (see below). + * However, since we have fired "sighted" during movement calculations + * this is a workaround to prevent a crash. + */ if(move_recorder != NULL) { move_recorder->add_movement(route.front(),*step); } diff --git a/src/actions.hpp b/src/actions.hpp index e01bc860ec7..fa220205d6a 100644 --- a/src/actions.hpp +++ b/src/actions.hpp @@ -12,8 +12,10 @@ See the COPYING file for more details. */ -//! @file actions.hpp -//! Various functions which implement in-game events and commands. +/** + * @file actions.hpp + * Various functions which implement in-game events and commands. + */ #ifndef ACTIONS_H_INCLUDED #define ACTIONS_H_INCLUDED @@ -44,56 +46,60 @@ bool can_recruit_on(const gamemap& map, const gamemap::location& leader, const g struct end_level_exception; -//! Function which recruits a unit into the game. -// A copy of u will be created and inserted as the new recruited unit. -// If need_castle is true, then the new unit must be on the same castle -// as the leader of the team is on the keep of. -// -// If preferred_location is in a valid location, it will be used, -// otherwise a valid location will be arbitrarily chosen. -// If disp is not NULL, the new unit will be faded in. -// -// If the unit cannot be recruited, then a human-readable message -// describing the reason will be returned. -// On success, the return string is empty. +/** + * Function which recruits a unit into the game. + * A copy of u will be created and inserted as the new recruited unit. + * If need_castle is true, then the new unit must be on the same castle + * as the leader of the team is on the keep of. + * + * If preferred_location is in a valid location, it will be used, + * otherwise a valid location will be arbitrarily chosen. + * If disp is not NULL, the new unit will be faded in. + * + * If the unit cannot be recruited, then a human-readable message + * describing the reason will be returned. + * On success, the return string is empty. + */ std::string recruit_unit(const gamemap& map, const int side, unit_map& units, unit u, gamemap::location& recruit_location,const bool is_recall, const bool show=false,const bool need_castle=true, const bool full_movement=false,const bool wml_triggered=false); -//! Computes the statistics of a battle between an attacker and a defender unit. +/** Computes the statistics of a battle between an attacker and a defender unit. */ class battle_context { public: - //! Structure describing the statistics of a unit involved in the battle. + /** Structure describing the statistics of a unit involved in the battle. */ struct unit_stats { - const attack_type *weapon; // The weapon used by the unit to attack the opponent, or NULL if there is none. - int attack_num; // Index into unit->attacks() or -1 for none. - bool is_attacker; // True if the unit is the attacker. - bool is_poisoned; // True if the unit is poisoned at the beginning of the battle. - bool is_slowed; // True if the unit is slowed at the beginning of the battle. - bool slows; // Attack slows opponent when it hits. - bool drains; // Attack drains opponent when it hits. - bool stones; // Attack turns opponent to stone when it hits. - bool plagues; // Attack turns opponent into a zombie when fatal. - bool poisons; // Attack poisons opponent when it hits. - bool backstab_pos; // True if the attacker is in *position* to backstab the defender (this is used to - // determine whether to apply the backstab bonus in case the attacker has backstab). - bool swarm; // Attack has swarm special. - bool firststrike; // Attack has firststrike special. + const attack_type *weapon; /**< The weapon used by the unit to attack the opponent, or NULL if there is none. */ + int attack_num; /**< Index into unit->attacks() or -1 for none. */ + bool is_attacker; /**< True if the unit is the attacker. */ + bool is_poisoned; /**< True if the unit is poisoned at the beginning of the battle. */ + bool is_slowed; /**< True if the unit is slowed at the beginning of the battle. */ + bool slows; /**< Attack slows opponent when it hits. */ + bool drains; /**< Attack drains opponent when it hits. */ + bool stones; /**< Attack turns opponent to stone when it hits. */ + bool plagues; /**< Attack turns opponent into a zombie when fatal. */ + bool poisons; /**< Attack poisons opponent when it hits. */ + bool backstab_pos; /**< + * True if the attacker is in *position* to backstab the defender (this is used to + * determine whether to apply the backstab bonus in case the attacker has backstab). + */ + bool swarm; /**< Attack has swarm special. */ + bool firststrike; /**< Attack has firststrike special. */ - unsigned int rounds; // Berserk special can force us to fight more than one round. - unsigned int hp; // Hitpoints of the unit at the beginning of the battle. - unsigned int max_hp; // Maximum hitpoints of the unit. - unsigned int chance_to_hit; // Effective chance to hit as a percentage (all factors accounted for). - int damage; // Effective damage of the weapon (all factors accounted for). - int slow_damage; // Effective damage if unit becomes slowed (== damage, if already slowed) - unsigned int num_blows; // Effective number of blows, takes swarm into account. - unsigned int swarm_min; // Minimum number of blows with swarm (equal to num_blows if swarm isn't used). - unsigned int swarm_max; // Maximum number of blows with swarm (equal to num_blows if swarm isn't used). + unsigned int rounds; /**< Berserk special can force us to fight more than one round. */ + unsigned int hp; /**< Hitpoints of the unit at the beginning of the battle. */ + unsigned int max_hp; /**< Maximum hitpoints of the unit. */ + unsigned int chance_to_hit; /**< Effective chance to hit as a percentage (all factors accounted for). */ + int damage; /**< Effective damage of the weapon (all factors accounted for). */ + int slow_damage; /**< Effective damage if unit becomes slowed (== damage, if already slowed) */ + unsigned int num_blows; /**< Effective number of blows, takes swarm into account. */ + unsigned int swarm_min; /**< Minimum number of blows with swarm (equal to num_blows if swarm isn't used). */ + unsigned int swarm_max; /**< Maximum number of blows with swarm (equal to num_blows if swarm isn't used). */ - std::string plague_type; // The plague type used by the attack, if any. + std::string plague_type; /**< The plague type used by the attack, if any. */ unit_stats(const unit &u, const gamemap::location& u_loc, int u_attack_num, bool attacking, @@ -104,20 +110,22 @@ public: const gamestatus& status, const gamemap& map); ~unit_stats(); - //! Dumps the statistics of a unit on stdout. Remove it eventually. + /** Dumps the statistics of a unit on stdout. Remove it eventually. */ void dump() const; }; - // If no attacker_weapon is given, we select the best one, - // based on harm_weight (1.0 means 1 hp lost counters 1 hp damage, - // 0.0 means we ignore harm weight). - // prev_def is for predicting multiple attacks against a defender. + /** + * If no attacker_weapon is given, we select the best one, + * based on harm_weight (1.0 means 1 hp lost counters 1 hp damage, + * 0.0 means we ignore harm weight). + * prev_def is for predicting multiple attacks against a defender. + */ battle_context(const gamemap& map, const std::vector& teams, const unit_map& units, const gamestatus& status, const gamemap::location& attacker_loc, const gamemap::location& defender_loc, int attacker_weapon = -1, int defender_weapon = -1, double aggression = 0.0, const combatant *prev_def = NULL, const unit* attacker_ptr=NULL); - // Used by the AI which caches unit_stats + /** Used by the AI which caches unit_stats */ battle_context(const unit_stats &att, const unit_stats &def); battle_context(const battle_context &other); @@ -125,17 +133,17 @@ public: battle_context& operator=(const battle_context &other); - //! This method returns the statistics of the attacker. + /** This method returns the statistics of the attacker. */ const unit_stats& get_attacker_stats() const { return *attacker_stats_; } - //! This method returns the statistics of the defender. + /** This method returns the statistics of the defender. */ const unit_stats& get_defender_stats() const { return *defender_stats_; } - //! Get the simulation results. + /** Get the simulation results. */ const combatant &get_attacker_combatant(const combatant *prev_def = NULL); const combatant &get_defender_combatant(const combatant *prev_def = NULL); - //! Given this harm_weight, is this attack better than that? + /** Given this harm_weight, is this attack better than that? */ bool better_attack(class battle_context &that, double harm_weight); private: @@ -154,14 +162,14 @@ private: const gamestatus& status, const gamemap::location& attacker_loc, const gamemap::location& defender_loc, const combatant *prev_def); - // Statistics of the units. + /** Statistics of the units. */ unit_stats *attacker_stats_, *defender_stats_; - // Outcome of simulated fight. + /** Outcome of simulated fight. */ combatant *attacker_combatant_, *defender_combatant_; }; -//! Executes an attack. +/** Executes an attack. */ class attack { public: attack(game_display& gui, const gamemap& map, @@ -205,71 +213,92 @@ class attack { }; -//! Given the location of a village, will return the 0-based index -//! of the team that currently owns it, and -1 if it is unowned. +/** + * Given the location of a village, will return the 0-based index + * of the team that currently owns it, and -1 if it is unowned. + */ int village_owner(const gamemap::location& loc, const std::vector& teams); -//! Makes it so the village at the given location -//! is owned by the given 0-based team number. -//! Returns true if getting the village triggered a mutating event. +/** + * Makes it so the village at the given location + * is owned by the given 0-based team number. + * Returns true if getting the village triggered a mutating event. + */ bool get_village(const gamemap::location& loc, game_display& disp, std::vector& teams, size_t team_num, const unit_map& units, int *time_bonus = NULL); -//! Given the 1-based side, will find the leader of that side, -//! and return an iterator to the leader +/** + * Given the 1-based side, will find the leader of that side, + * and return an iterator to the leader + */ unit_map::iterator find_leader(unit_map& units, int side); unit_map::const_iterator find_leader(const unit_map& units, int side); -//! Resets resting for all units on this side: should be called after calculate_healing(). -//! @todo FIXME: Try moving this to unit::new_turn, then move it above calculate_healing(). +/** + * Resets resting for all units on this side: should be called after calculate_healing(). + * @todo FIXME: Try moving this to unit::new_turn, then move it above calculate_healing(). + */ void reset_resting(unit_map& units, unsigned int side); -//! Calculates healing for all units for the given side. -//! Should be called at the beginning of a side's turn. +/** + * Calculates healing for all units for the given side. + * Should be called at the beginning of a side's turn. + */ void calculate_healing(game_display& disp, const gamemap& map, unit_map& units, unsigned int side, const std::vector& teams, bool update_display); -//! Function which, given the location of a unit that is advancing, -//! and the name of the unit it is advancing to, -//! Will return the advanced version of this unit. -//! (with traits and items retained). +/** + * Function which, given the location of a unit that is advancing, + * and the name of the unit it is advancing to, + * Will return the advanced version of this unit. + * (with traits and items retained). + */ unit get_advanced_unit(unit_map& units, const gamemap::location& loc, const std::string& advance_to); -//! Function which will advance the unit at loc to 'advance_to'. -// Note that 'loc' is not a reference, because if it were a reference, -// we couldn't safely pass in a reference to the item in the map -// that we're going to delete, since deletion would invalidate the reference. +/** + * Function which will advance the unit at loc to 'advance_to'. + * Note that 'loc' is not a reference, because if it were a reference, + * we couldn't safely pass in a reference to the item in the map + * that we're going to delete, since deletion would invalidate the reference. + */ void advance_unit(unit_map& units, gamemap::location loc, const std::string& advance_to); -//! function which tests if the unit at loc is currently affected by leadership. -//! (i.e. has a higher-level 'leadership' unit next to it). -//! If it does, then the location of the leader unit will be returned, -//! Otherwise gamemap::location::null_location will be returned. -//! If 'bonus' is not NULL, the % bonus will be stored in it. +/** + * function which tests if the unit at loc is currently affected by leadership. + * (i.e. has a higher-level 'leadership' unit next to it). + * If it does, then the location of the leader unit will be returned, + * Otherwise gamemap::location::null_location will be returned. + * If 'bonus' is not NULL, the % bonus will be stored in it. + */ gamemap::location under_leadership(const unit_map& units, const gamemap::location& loc, int* bonus=NULL); -//! Checks to see if a side has won, and will throw -//! an end_level_exception if one has. -//! Will also remove control of villages from sides with dead leaders. +/** + * Checks to see if a side has won, and will throw + * an end_level_exception if one has. + * Will also remove control of villages from sides with dead leaders. + */ void check_victory(unit_map& units, std::vector& teams, display& disp); -//! Gets the time of day at a certain tile. -//! Certain tiles may have a time of day that differs -//! from 'the' time of day, if a unit that illuminates -//! is in that tile or adjacent. +/** + * Gets the time of day at a certain tile. + * Certain tiles may have a time of day that differs from 'the' time of day, if + * a unit that illuminates is in that tile or adjacent. + */ time_of_day timeofday_at(const gamestatus& status, const unit_map& units, const gamemap::location& loc, const gamemap& map); -//! Returns the amount that a unit's damage should be multiplied by -//! due to the current time of day. +/** + * Returns the amount that a unit's damage should be multiplied by + * due to the current time of day. + */ int combat_modifier(const gamestatus& status, const unit_map& units, const gamemap::location& loc, @@ -277,7 +306,7 @@ int combat_modifier(const gamestatus& status, bool is_fearless, const gamemap& map); -//! Records information to be able to undo a movement. +/** Records information to be able to undo a movement. */ struct undo_action { undo_action(const unit& u, const std::vector& rt, @@ -314,11 +343,13 @@ struct undo_action { typedef std::deque undo_list; -//! function which moves a unit along the sequence of locations given by steps. -//! If the unit cannot make it completely along the path this turn, -//! a goto order will be set. -//! If move_recorder is not NULL, the move will be recorded in it. -//! If undos is not NULL, undo information will be added. +/** + * function which moves a unit along the sequence of locations given by steps. + * If the unit cannot make it completely along the path this turn, + * a goto order will be set. + * If move_recorder is not NULL, the move will be recorded in it. + * If undos is not NULL, undo information will be added. + */ size_t move_unit(game_display* disp, const gamemap& map, unit_map& units, std::vector& teams, @@ -327,24 +358,30 @@ size_t move_unit(game_display* disp, gamemap::location *next_unit = NULL, bool continue_move = false, bool should_clear_shroud=true); -//! Function which recalculates the fog. +/** Function which recalculates the fog. */ void recalculate_fog(const gamemap& map, unit_map& units, std::vector& teams, int team); -//! Function which will clear shroud away for the given 0-based team -//! based on current unit positions. -//! Returns true if some shroud is actually cleared away. +/** + * Function which will clear shroud away for the given 0-based team + * based on current unit positions. + * Returns true if some shroud is actually cleared away. + */ bool clear_shroud(game_display& disp, const gamemap& map, unit_map& units, std::vector& teams, int team); -//! Function to apply pending shroud changes in the undo stack. -//! It needs tons of parameters because it calls clear_shroud(...) (see above) +/** + * Function to apply pending shroud changes in the undo stack. + * It needs tons of parameters because it calls clear_shroud(...) (see above) + */ void apply_shroud_changes(undo_list& undos, game_display* disp, const gamemap& map, unit_map& units, std::vector& teams, int team); -//! Will return true iff the unit at 'loc' has any possible moves -//! it can do (including attacking etc). +/** + * Will return true iff the unit at 'loc' has any possible moves + * it can do (including attacking etc). + */ bool unit_can_move(const gamemap::location& loc, const unit_map& units, const gamemap& map, const std::vector& teams); @@ -355,16 +392,18 @@ namespace victory_conditions { void set_carryover_add(const bool add); } -//! Function to check if an attack will satisfy the requirements for backstab. -//! Input: -//! - the location from which the attack will occur, -//! - the defending unit location, -//! - the list of units on the map and -//! - the list of teams. -//! The defender and opposite units should be in place already. -//! The attacking unit doesn't need to be, but if it isn't, -//! an external check should be made to make sure the opposite unit -//! isn't also the attacker. +/** + * Function to check if an attack will satisfy the requirements for backstab. + * Input: + * - the location from which the attack will occur, + * - the defending unit location, + * - the list of units on the map and + * - the list of teams. + * The defender and opposite units should be in place already. + * The attacking unit doesn't need to be, but if it isn't, + * an external check should be made to make sure the opposite unit + * isn't also the attacker. + */ bool backstab_check(const gamemap::location& attacker_loc, const gamemap::location& defender_loc, const unit_map& units, const std::vector& teams);