Update doxygen comment style.

This commit is contained in:
Mark de Wever 2008-06-18 20:16:34 +00:00
parent badacfd16d
commit 19e6d51744
2 changed files with 176 additions and 132 deletions

View file

@ -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<team>& 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<team>& 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<team>& 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);
}

View file

@ -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<team>& 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<team>& 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<team>& 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<team>& 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<team>& 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<gamemap::location>& rt,
@ -314,11 +343,13 @@ struct undo_action {
typedef std::deque<undo_action> 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<team>& 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<team>& 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<team>& 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<team>& 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<team>& 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<team>& teams);