doxygen, comments

src/game_events.cpp

@@ -12,6 +12,9 @@
    See the COPYING file for more details.
 */
 
+//! @file game_events.cpp 
+//! Processing of WML-events.
+
 #include "global.hpp"
 #include "actions.hpp"
 #include "construct_dialog.hpp"
@@ -84,7 +87,7 @@ public:
 	}
 };
 
-} //end anonymous namespace
+} // end anonymous namespace (1)
 
 #ifdef _MSC_VER
 // std::getline might be broken in Visual Studio so show a warning
@@ -97,16 +100,18 @@ public:
 #endif
 
 /**
- * shows the errors encountered in WML thusfar, to avoid a lot of the same messages
- * to be shown, identical messages are shown once with the between braces the number
- * of times that message was encountered. The order in which the messages are shown
- * does not need to be the order in which these messages are encountered.
- * Messages are always written to std::cerr
+ * Shows a summary of the errors encountered in WML thusfar, 
+ * to avoid a lot of the same messages to be shown. 
+ * Identical messages are shown once, with (between braces)
+ * the number of times that message was encountered. 
+ * The order in which the messages are shown does not need 
+ * to be the order in which these messages are encountered.
+ * Messages are always written to std::cerr.
  */
 static void show_wml_errors()
 {
-	// Get all unique messages in messages with the number of encounters for
-	// these messages
+	// Get all unique messages in messages, 
+	// with the number of encounters for these messages
 	std::map<std::string, int> messages;
 	while(true) {
 		std::string msg;
@@ -126,10 +131,10 @@ static void show_wml_errors()
 			messages[msg]++;
 		}
 	}
-	// make sure the eof flag is cleared otherwise no new messages are shown
+	// Make sure the eof flag is cleared otherwise no new messages are shown
 	lg::wml_error.clear();
 
-	// show the messages collected
+	// Show the messages collected
 	std::string caption = "Deprecated WML found";
 	for(std::map<std::string, int>::const_iterator itor = messages.begin();
 			itor != messages.end(); ++itor) {
@@ -159,8 +164,8 @@ bool internal_conditional_passed(const unit_map* units,
                         const vconfig cond, bool& backwards_compat)
 {
 
-	//if the if statement requires we have a certain unit, then
-	//check for that.
+	// If the if statement requires we have a certain unit, 
+	// then check for that.
 	const vconfig::child_list& have_unit = cond.get_children("have_unit");
 	backwards_compat = backwards_compat && have_unit.empty();
 	for(vconfig::child_list::const_iterator u = have_unit.begin(); u != have_unit.end(); ++u) {
@@ -180,8 +185,8 @@ bool internal_conditional_passed(const unit_map* units,
 		}
 	}
 
-	//if the if statement requires we have a certain location, then
-	//check for that.
+	// If the if statement requires we have a certain location, 
+	// then check for that.
 	const vconfig::child_list& have_location = cond.get_children("have_location");
 	backwards_compat = backwards_compat && have_location.empty();
 	for(vconfig::child_list::const_iterator v = have_location.begin(); v != have_location.end(); ++v) {
@@ -193,8 +198,8 @@ bool internal_conditional_passed(const unit_map* units,
 		}
 	}
 
-	//check against each variable statement to see if the variable
-	//matches the conditions or not
+	// Check against each variable statement, 
+	// to see if the variable matches the conditions or not.
 	const vconfig::child_list& variables = cond.get_children("variable");
 	backwards_compat = backwards_compat && variables.empty();
 	for(vconfig::child_list::const_iterator var = variables.begin(); var != variables.end(); ++var) {
@@ -261,7 +266,7 @@ bool conditional_passed(const unit_map* units,
 		utils::string_bool(cond["backwards_compat"],true);
 	bool matches = internal_conditional_passed(units, cond, allow_backwards_compat);
 
-	//handle [and], [or], and [not] with in-order precedence
+	// Handle [and], [or], and [not] with in-order precedence
 	int or_count = 0;
 	config::all_children_iterator cond_i = cond.get_config().ordered_begin();
 	config::all_children_iterator cond_end = cond.get_config().ordered_end();
@@ -270,19 +275,19 @@ bool conditional_passed(const unit_map* units,
 		const std::string& cond_name = *((*cond_i).first);
 		const vconfig cond_filter(&(*((*cond_i).second)));
 
-		//handle [and]
+		// Handle [and]
 		if(cond_name == "and")
 		{
 			matches = matches && conditional_passed(units, cond_filter, backwards_compat);
 			backwards_compat = false;
 		}
-		//handle [or]
+		// Handle [or]
 		else if(cond_name == "or")
 		{
 			matches = matches || conditional_passed(units, cond_filter, backwards_compat);
 			++or_count;
 		}
-		//handle [not]
+		// Handle [not]
 		else if(cond_name == "not")
 		{
 			matches = matches && !conditional_passed(units, cond_filter, backwards_compat);
@@ -290,12 +295,12 @@ bool conditional_passed(const unit_map* units,
 		}
 		++cond_i;
 	}
-	//check for deprecated [or] syntax
+	// Check for deprecated [or] syntax
 	if(matches && or_count > 1 && allow_backwards_compat)
 	{
 		lg::wml_error << "possible deprecated [or] syntax: now forcing re-interpretation\n";
-		//for now we will re-interpret it according to the old rules
-		//but this should be later to prevent re-interpretation errors
+		//! @todo For now we will re-interpret it according to the old rules,
+		// but this should be later to prevent re-interpretation errors.
 		const vconfig::child_list& orcfgs = cond.get_children("or");
 		for(unsigned int i=0; i < orcfgs.size(); ++i) {
 			if(conditional_passed(units, orcfgs[i])) {
@@ -307,7 +312,7 @@ bool conditional_passed(const unit_map* units,
 	return matches;
 }
 
-} //end namespace game_events
+} // end namespace game_events (1)
 
 namespace {
 
@@ -318,12 +323,12 @@ This variable controls the maximum number of hexes in a map, that can be parsed
 It was set to 1024 before and for larger maps this could become a problem. So it is raised to 
 65536 now, which can feature a map of size 256*256 (maps really shouldn't be bigger than that :-).
 This constant also controls the maximum number of loops for a WML while loop (hence its name).
-If this is felt to be too high now, we must split it into two constants, but i don't feel the need
-at the moment.
+If this is felt to be too high now, we must split it into two constants, 
+but i don't feel the need at the moment.
 */
 const size_t MaxLoop = 65536;
 
-} //end anonymous namespace
+} // end anonymous namespace (2)
 
 static bool events_init() { return screen != NULL; }
 
@@ -413,7 +418,7 @@ private:
 	vconfig cfg_;
 };
 
-} //end anonymous namespace
+} // end anonymous namespace (3)
 
 static gamemap::location cfg_to_loc(const vconfig cfg,int defaultx = 0, int defaulty = 0)
 {
@@ -432,8 +437,7 @@ namespace {
 
 std::multimap<std::string,event_handler> events_map;
 
-//this function handles all the different types of actions that can be triggered
-//by an event.
+//! Handles all the different types of actions that can be triggered by an event.
 bool event_handler::handle_event_command(const queued_event& event_info,
 		const std::string& cmd, const vconfig cfg, bool& mutated)
 {
@@ -441,18 +445,18 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	LOG_NG << "handling command: '" << cmd << "'\n";
 
 	bool rval = true;
-	//sub commands that need to be handled in a guaranteed ordering
+	// Sub commands that need to be handled in a guaranteed ordering
 	if(cmd == "command") {
 		if(!handle_event(event_info, cfg)) {
 			mutated = false;
 		}
 	}
 
-	//allow undo sets the flag saying whether the event has mutated the game to false
+	// Allow undo sets the flag saying whether the event has mutated the game to false
 	else if(cmd == "allow_undo") {
 		mutated = false;
 	}
-	//change shroud settings for portions of the map
+	// Change shroud settings for portions of the map
 	else if(cmd == "remove_shroud" || cmd == "place_shroud") {
 		const bool remove = cmd == "remove_shroud";
 
@@ -476,12 +480,12 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	}
 
 
-	//teleport a unit from one location to another
+	// Teleport a unit from one location to another
 	else if(cmd == "teleport") {
 
 		unit_map::iterator u = units->find(event_info.loc1);
 
-		//search for a valid unit filter, and if we have one, look for the matching unit
+		// Search for a valid unit filter, and if we have one, look for the matching unit
 		const vconfig filter = cfg.child("filter");
 		if(!filter.null()) {
 			for(u = units->begin(); u != units->end(); ++u){
@@ -490,7 +494,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 
-		//we have found a unit that matches the filter
+		// We have found a unit that matches the filter
 		if(u != units->end()) {
 			const gamemap::location dst = cfg_to_loc(cfg);
 			if(dst != u->first && game_map->on_board(dst)) {
@@ -518,10 +522,10 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//remove units from being turned to stone
+	// Remove units from being turned to stone
 	else if(cmd == "unstone") {
 		const vconfig filter = cfg.child("filter");
-		//store which side will need a shroud/fog update
+		// Store which side will need a shroud/fog update
 		std::vector<bool> clear_fog_side(teams->size(),false);
 
 		for(unit_map::iterator i = units->begin(); i != units->end(); ++i) {
@@ -540,7 +544,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//allow a side to recruit a new type of unit
+	// Allow a side to recruit a new type of unit
 	else if(cmd == "allow_recruit") {
 		std::string side = cfg["side"];
 		wassert(state_of_game != NULL);
@@ -564,7 +568,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//remove the ability to recruit a unit from a certain side
+	// Remove the ability to recruit a unit from a certain side
 	else if(cmd == "disallow_recruit") {
 		std::string side = cfg["side"];
 		wassert(state_of_game != NULL);
@@ -670,7 +674,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//an award of gold to a particular side
+	// An award of gold to a particular side
 	else if(cmd == "gold") {
 		std::string side = cfg["side"];
 		std::string amount = cfg["amount"];
@@ -683,7 +687,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//modifications of some attributes of a side: gold, income, team name
+	// Modifications of some attributes of a side: gold, income, team name
 	else if(cmd == "modify_side") {
 		std::cerr << "modifying side...\n";
 		std::string side = cfg["side"];
@@ -712,7 +716,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 	}
-	//stores of some attributes of a side: gold, income, team name
+	// Stores of some attributes of a side: gold, income, team name
 	else if(cmd == "store_side" || cmd == "store_gold") {
 		t_string *gold_store;
 		std::string side = cfg["side"];
@@ -824,7 +828,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//provide a means of specifying win/loss conditions:
+	// Provide a means of specifying win/loss conditions:
 	// [event]
 	// name=prestart
 	// [objectives]
@@ -853,9 +857,9 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	//
 	// If side is set to 0, the new objectives are added to each player.
 	//
-	// The new objectives will be automatically displayed, but only to the
-	// player whose objectives did change, and only when it's this player's
-	// turn.
+	// The new objectives will be automatically displayed, 
+	// but only to the player whose objectives did change, 
+	// and only when it's this player's turn.
 	else if(cmd == "objectives") {
 		const std::string win_str = "@";
 		const std::string lose_str = "#";
@@ -928,14 +932,14 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	}
 
 
-	//setting a variable
+	// Setting a variable
 	else if(cmd == "set_variable") {
 		wassert(state_of_game != NULL);
 
 		const std::string name = cfg["name"];
 		t_string& var = state_of_game->get_variable(name);
 
-		const t_string& literal = cfg.get_attribute("literal"); //no $var substitution
+		const t_string& literal = cfg.get_attribute("literal"); 	// no $var substitution
 		if(literal.empty() == false) {
 			var = literal;
 		}
@@ -945,7 +949,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			var = value;
 		}
 
-		const t_string format = cfg["format"]; //deprecated, use value
+		const t_string format = cfg["format"];	// Deprecated, use value
 		if(format.empty() == false) {
 			var = format;
 		}
@@ -1001,8 +1005,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 
-		// Note maybe we add more options later eg strftime formatting
-		// for now make the stamp mandatory
+		// Note: maybe we add more options later, eg. strftime formatting.
+		// For now make the stamp mandatory.
 		const std::string time = cfg["time"];
 		if(time == "stamp") {
 			char buf[50];
@@ -1010,15 +1014,15 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			var = buf;
 		}
 
-		// random generation works as follows:
+		// Random generation works as follows:
 		// random=[comma delimited list]
 		// Each element in the list will be considered a separate choice,
 		// unless it contains "..". In this case, it must be a numerical
-		// range. (i.e. -1..-10, 0..100, -10..10, etc)
+		// range (i.e. -1..-10, 0..100, -10..10, etc).
 		const std::string random = cfg["random"];
 		if(random.empty() == false) {
 			std::string random_value;
-			//if we're not replaying create a random number
+			// If we're not replaying, create a random number
 			if(get_replay_source().at_end()) {
 				std::string word;
 				std::vector<std::string> words;
@@ -1039,12 +1043,12 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 
 					if (tmp == std::string::npos) {
-						// treat this element as a string
+						// Treat this element as a string
 						ranges.push_back(std::pair<int, int>(0,0));
 						num_choices += 1;
 					}
 					else {
-						// treat as a numerical range
+						// Treat as a numerical range
 						const std::string first = word.substr(0, tmp);
 						const std::string second = word.substr(tmp+2,
 								random.length());
@@ -1085,7 +1089,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				recorder.set_random_value(random_value.c_str());
 			}
 
-			//otherwise get the random value from the replay data
+			// Otherwise get the random value from the replay data
 			else {
 				const config* const action = get_replay_source().get_next_action();
 				if(action == NULL || action->get_children("random_number").empty()) {
@@ -1099,7 +1103,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//conditional statements
+	// Conditional statements
 	else if(cmd == "if" || cmd == "while") {
 		log_scope(cmd);
 		const size_t max_iterations = (cmd == "if" ? 1 : MaxLoop);
@@ -1113,8 +1117,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				break;
 			}
 
-			//if the if statement passed, then execute all 'then' statements,
-			//otherwise execute 'else' statements
+			// If the if statement passed, then execute all 'then' statements,
+			// otherwise execute 'else' statements
 			const vconfig::child_list commands = cfg.get_children(type);
 			for(vconfig::child_list::const_iterator cmd = commands.begin();
 			cmd != commands.end(); ++cmd) {
@@ -1127,14 +1131,14 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 	else if(cmd == "role") {
 
-		//get a list of the types this unit can be
+		// Get a list of the types this unit can be
 		std::vector<std::string> types = utils::split(cfg["type"]);
 		if (types.size() == 0) types.push_back("");
 
                 std::vector<std::string> sides = utils::split(cfg["side"]);
 
-		//iterate over all the types, and for each type, try to find
-		//a unit that matches
+		// Iterate over all the types, and for each type, 
+		// try to find a unit that matches
 		std::vector<std::string>::iterator ti;
 		for(ti = types.begin(); ti != types.end(); ++ti) {
 			config item = cfg.get_config();
@@ -1165,7 +1169,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 					if(!player)
 						continue;
 
-					//iterate over the units, and try to find one that matches
+					// Iterate over the units, and try to find one that matches
 					std::vector<unit>::iterator ui;
 					for(ui = player->available_units.begin();
 							ui != player->available_units.end(); ++ui) {
@@ -1185,7 +1189,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				for(pi=state_of_game->players.begin();
 						pi!=state_of_game->players.end(); ++pi) {
 					std::vector<unit>::iterator ui;
-					//iterate over the units, and try to find one that matches
+					// Iterate over the units, and try to find one that matches
 					for(ui = pi->second.available_units.begin();
 							ui != pi->second.available_units.end(); ++ui) {
 						wassert(game_data_ptr != NULL);
@@ -1201,7 +1205,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				}
 			}
 
-			//if we found a unit, we don't have to keep going.
+			// Stop searching if we found a unit:
                         if(found)
 				break;
 		}
@@ -1238,7 +1242,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//hiding units
+	// Hiding units
 	else if(cmd == "hide_unit") {
 		const gamemap::location loc = cfg_to_loc(cfg);
 		unit_map::iterator u = units->find(loc);
@@ -1252,7 +1256,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	else if(cmd == "unhide_unit") {
 		const gamemap::location loc = cfg_to_loc(cfg);
 		unit_map::iterator u;
-		// unhide all for backward compatibility
+		// Unhide all for backward compatibility
 		for(u =  units->begin(); u != units->end() ; u++) {
 			u->second.set_hidden(false);
 			screen->invalidate(loc);
@@ -1260,7 +1264,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//adding new items
+	// Adding new items
 	else if(cmd == "item") {
 		gamemap::location loc = cfg_to_loc(cfg);
 		std::string img = cfg["image"];
@@ -1305,7 +1309,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		soundsources->remove(cfg["id"]);
 	}
 
-	//changing the terrain
+	// Changing the terrain
 	else if(cmd == "terrain") {
 		const std::vector<gamemap::location> locs = multiple_locs(cfg);
 		
@@ -1334,7 +1338,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//creating a mask of the terrain
+	// Creating a mask of the terrain
 	else if(cmd == "terrain_mask") {
 		gamemap::location loc = cfg_to_loc(cfg, 1, 1);
 
@@ -1353,7 +1357,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		screen->rebuild_all();
 	}
 
-	//if we should spawn a new unit on the map somewhere
+	// If we should spawn a new unit on the map somewhere
 	else if(cmd == "unit") {
 		wassert(game_data_ptr != NULL);
 		wassert(units != NULL);
@@ -1397,14 +1401,14 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//if we should recall units that match a certain description
+	// If we should recall units that match a certain description
 	else if(cmd == "recall") {
 		LOG_NG << "recalling unit...\n";
 		bool unit_recalled = false;
 		config unit_filter(cfg.get_config());
-		//prevent the recall unit filter from using the location as a criterion
-		// FIXME: we should design the WML to avoid these types of collisions;
-		// filters should be named consistently and always have a distinct scope
+		// Prevent the recall unit filter from using the location as a criterion
+		//! @todo FIXME: we should design the WML to avoid these types of collisions;
+		// filters should be named consistently and always have a distinct scope.
 		unit_filter["x"] = "";
 		unit_filter["y"] = "";
 		for(int index = 0; !unit_recalled && index < int(teams->size()); ++index) {
@@ -1427,7 +1431,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				if(game_events::unit_matches_filter(*u, &unit_filter, gamemap::location())) {
 					gamemap::location loc = cfg_to_loc(cfg);
 					unit to_recruit(*u);
-					avail.erase(u); //erase before recruiting, since recruiting can fire more events
+					avail.erase(u); 	// Erase before recruiting, since recruiting can fire more events
 					unit_mutations++;
 					recruit_unit(*game_map,index+1,*units,to_recruit,loc,utils::string_bool(cfg["show"],true),false,true);
 					unit_recalled = true;
@@ -1441,7 +1445,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		std::string id = cfg["id"];
 		wassert(state_of_game != NULL);
 
-		//if this item has already been used
+		// If this item has already been used
 		if(id != "" && used_items.count(id))
 			return rval;
 
@@ -1475,7 +1479,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			screen->select_hex(event_info.loc1);
 			screen->invalidate_unit();
 
-			//mark that this item won't be used again
+			// Mark this item as used up.
 			used_items.insert(id);
 		} else {
 			text = cfg["cannot_use_message"];
@@ -1489,7 +1493,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				surface.assign(image::get_image(image));
 			}
 
-			//this will redraw the unit, with its new stats
+			// Redraw the unit, with its new stats
 			screen->draw();
 
 			const std::string duration_str = cfg["duration"];
@@ -1511,7 +1515,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//displaying a message on-screen
+	// Display a message on-screen
 	else if(cmd == "print") {
 		std::string text = cfg["text"];
 		std::string size_str = cfg["size"];
@@ -1529,7 +1533,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 		SDL_Color colour = {red,green,blue,255};
 
-		//remove any old one.
+		// Remove any old message.
 		if (floating_label)
 			font::remove_floating_label(floating_label);
 
@@ -1543,12 +1547,12 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	}
 				
 	else if(cmd == "deprecated_message") {
-		// note since only used for deprecated things no need to translate the string
+		// Note: no need to translate the string, since only used for deprecated things.
 		const std::string message = cfg["message"];
 		lg::wml_error << message << '\n';
 	}
 
-	//displaying a message dialog
+	// Display a message dialog
 	else if(cmd == "message") {
 		unit_map::iterator speaker = units->end();
 
@@ -1566,8 +1570,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 
 		if(speaker == units->end() && speaker_str != "narrator") {
-			//no matching unit found, so the dialog can't come up
-			//continue onto the next message
+			// No matching unit found, so the dialog can't come up.
+			// Continue onto the next message.
 			WRN_NG << "cannot show message\n";
 			return rval;
 		}
@@ -1639,8 +1643,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 		LOG_DP << "showing dialog...\n";
 
-		//if we're not replaying, or if we are replaying and there is no choice
-		//to be made, show the dialog.
+		// If we're not replaying, or if we are replaying 
+		// and there is no choice to be made, show the dialog.
 		if(get_replay_source().at_end() || options.empty()) {
 			const t_string msg = cfg["message"];
 			const std::string duration_str = cfg["duration"];
@@ -1673,7 +1677,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 
-		//otherwise if a choice has to be made, get it from the replay data
+		// Otherwise if a choice has to be made, get it from the replay data
 		else {
 			const config* action = get_replay_source().get_next_action();
 			if (action != NULL && !action->get_children("start").empty()){
@@ -1687,7 +1691,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			option_chosen = atol(val.c_str());
 		}
 
-		//implement the consequences of the choice
+		// Implement the consequences of the choice
 		if(options.empty() == false) {
 			if(size_t(option_chosen) >= menu_items.size()) {
 				std::stringstream errbuf;
@@ -1708,7 +1712,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	}
 
 	else if(cmd == "kill") {
-		//Use (x,y) iteration because firing events ruins unit_map iteration
+		// Use (x,y) iteration, because firing events ruins unit_map iteration
 		for(gamemap::location loc(0,0); loc.x < game_map->w(); ++loc.x) {
 			for(loc.y = 0; loc.y < game_map->h(); ++loc.y) {
 				unit_map::iterator un = units->find(loc);
@@ -1733,8 +1737,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 
-		//if the filter doesn't contain positional information, then it may match
-                //units on all recall lists.
+		// If the filter doesn't contain positional information, 
+		// then it may match units on all recall lists.
 		if(cfg["x"].empty() && cfg["y"].empty()) {
                   std::map<std::string, player_info>& players=state_of_game->players;
 
@@ -1755,12 +1759,12 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//adding of new events
+	// Adding of new events
 	else if(cmd == "event") {
 		new_handlers.push_back(event_handler(cfg.get_config()));
 	}
 
-	//setting of menu items
+	// Setting of menu items
 	else if(cmd == "set_menu_item") {
 		/* 
 		[set_menu_item]
@@ -1806,8 +1810,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			wmi_command_changes.push_back(wmi_command_change(id, new_command));
 		}
 	}
-	//unit serialization to and from variables
-	// FIXME: Check that store is automove bug safe
+	// Unit serialization to and from variables
+	//! @todo FIXME: Check that store is automove bug safe
 	else if(cmd == "store_unit") {
 		const config empty_filter;
 		vconfig filter = cfg.child("filter");
@@ -1900,7 +1904,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				std::string text = cfg["text"];
 				if(!text.empty())
 				{
-					//Print floating label
+					// Print floating label
 					std::string red_str = cfg["red"];
 					std::string green_str = cfg["green"];
 					std::string blue_str = cfg["blue"];
@@ -1916,17 +1920,17 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 				std::cerr << "advance = " << advance << '\n';
 				
 				if(utils::string_bool(cfg["advance"], true) && get_replay_source().at_end()) {
-					//Try to advance the unit
+					// Try to advance the unit
 
-					//FIXME: get player_number_ from the play_controller not from the WML vars
+					//! @todo FIXME: get player_number_ from the play_controller, not from the WML vars.
 					const t_string& side_str = state_of_game->get_variable("side_number");
 					const int side = lexical_cast_default<int>(side_str.base_str(), -1);
 
-					//Select advancement if it is on the playing side and the player is a human
+					// Select advancement if it is on the playing side and the player is a human
 					const bool sel = (side == static_cast<int>(u.side())
 					                 && (*teams)[side-1].is_human());
 
-					//The code in dialogs::advance_unit tests whether the unit can advance
+					// The code in dialogs::advance_unit tests whether the unit can advance
 					dialogs::advance_unit(*game_data_ptr, *game_map, *units, loc, *screen, !sel, true);
 				}
 
@@ -1963,7 +1967,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 	}
 
 	/* [store_villages] : store villages into an array
-	 * keys:
+	 * Keys:
 	 * - variable (mandatory): variable to store in
 	 * - side: if present, the village should be owned by this side (0=unowned villages)
 	 * - terrain: if present, filter the village types against this list of terrain types 
@@ -1981,7 +1985,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 		for(std::vector<gamemap::location>::const_iterator j = locs.begin(); j != locs.end(); ++j) {
 			bool matches = false;
-			if(cfg.has_attribute("side")) { //deprecated, use owner_side instead
+			if(cfg.has_attribute("side")) { 	// deprecated, use owner_side instead
 				lg::wml_error << "side key is no longer accepted in [store_villages],"
 					<< " use owner_side instead.\n";
 				config temp_cfg(cfg.get_config());
@@ -2019,13 +2023,13 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//command to take control of a village for a certain side
+	// Command to take control of a village for a certain side
 	else if(cmd == "capture_village") {
 		std::string side = cfg["side"];
 		wassert(state_of_game != NULL);
 		const int side_num = lexical_cast_default<int>(side);
-		//if 'side' is 0, then it will become an invalid index, and so
-		//the village will become neutral.
+		// If 'side' is 0, then it will become an invalid index, 
+		// and so the village will become neutral.
 		const size_t team_num = size_t(side_num-1);
 
 		const std::vector<gamemap::location> locs(multiple_locs(cfg));
@@ -2037,7 +2041,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 		}
 	}
 
-	//command to remove a variable
+	// Command to remove a variable
 	else if(cmd == "clear_variable") {
 		const std::string name = cfg["name"];
 		state_of_game->clear_variable(name);
@@ -2079,7 +2083,8 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 
 		unit_map::iterator u = units->find(event_info.loc1);
 
-		//search for a valid unit filter, and if we have one, look for the matching unit
+		// Search for a valid unit filter, 
+		// and if we have one, look for the matching unit
 		const vconfig filter = cfg.child("filter");
 		if(!filter.null()) {
 			for(u = units->begin(); u != units->end(); ++u){
@@ -2088,7 +2093,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 			}
 		}
 
-		//we have found a unit that matches the filter
+		// We have found a unit that matches the filter
 		if(u != units->end() && ! screen->fogged(u->first)) {
 			screen->highlight_hex(u->first);
 			screen->scroll_to_tile(u->first);
@@ -2123,7 +2128,7 @@ bool event_handler::handle_event_command(const queued_event& event_info,
 }
 
 static void commit_new_handlers() {
-	//commit any spawned events-within-events
+	// Commit any spawned events-within-events
 	while(new_handlers.size() > 0) {
 		event_handler& new_handler = new_handlers.back();
 		events_map.insert(std::pair<std::string,event_handler>(new_handler.name(),new_handler));
@@ -2134,7 +2139,7 @@ static void commit_new_handlers() {
 }
 
 static void commit_wmi_commands() {
-	//commit WML Menu Item command changes
+	// Commit WML Menu Item command changes
 	while(wmi_command_changes.size() > 0) {
 		wmi_command_change wcc = wmi_command_changes.back();
 		wml_menu_item*& mref = state_of_game->wml_menu_items[wcc.first];
@@ -2174,8 +2179,8 @@ bool event_handler::handle_event(const queued_event& event_info, const vconfig c
 
 		const std::pair<const std::string*,const config*> item = *i;
 
-		// If the user pressed escape, we skip any message that doesn't
-		// require them to make a choice.
+		// If the user pressed escape, we skip any message 
+		// that doesn't require them to make a choice.
 		if ((skip_messages) && (*item.first == "message")) {
 			if ((item.second)->get_children("option").size() == 0) {
 				continue;
@@ -2190,13 +2195,13 @@ bool event_handler::handle_event(const queued_event& event_info, const vconfig c
 		}
 	}
 
-	// We do this once event has completed any music alterations
+	// We do this once the event has completed any music alterations
 	sound::commit_music_changes();
 
 	return mutated;
 }
 
-} //end anonymous namespace
+} // end anonymous namespace (4)
 
 static bool process_event(event_handler& handler, const queued_event& ev)
 {
@@ -2265,16 +2270,16 @@ static bool process_event(event_handler& handler, const queued_event& ev)
 	}
 	if(ev.loc1.requires_unit() && filtered_unit1
 	&& (unit1 == units->end() || !ev.loc1.matches_unit(unit1->second))) {
-		//wrong or missing entity at src location
+		// Wrong or missing entity at src location
 		return false;
 	}
 	if(ev.loc2.requires_unit()  && filtered_unit2
 	&& (unit2 == units->end() || !ev.loc2.matches_unit(unit2->second))) {
-		//wrong or missing entity at dst location
+		// Wrong or missing entity at dst location
 		return false;
 	}
 
-	//the event hasn't been filtered out, so execute the handler
+	// The event hasn't been filtered out, so execute the handler
 	const bool res = handler.handle_event(ev);
 	if(ev.name == "select") {
 		state_of_game->last_selected = ev.loc1;
@@ -2298,8 +2303,8 @@ namespace game_events {
 
 bool matches_special_filter(const config* cfg, const vconfig filter)
 {
-	//FIXME: this filter should be deprecated and removed, 
-	//instead we should just auto-store $attacker_weapon and check it in a conditional
+	//! @todo FIXME: This filter should be deprecated and removed, 
+	// instead we should just auto-store $attacker_weapon and check it in a conditional
 
 	if(!cfg) {
 		return false;
@@ -2311,7 +2316,7 @@ bool matches_special_filter(const config* cfg, const vconfig filter)
 		}
 	}
 
-	//handle [and], [or], and [not] with in-order precedence
+	// Handle [and], [or], and [not] with in-order precedence
 	config::all_children_iterator cond_i = filter.get_config().ordered_begin();
 	config::all_children_iterator cond_end = filter.get_config().ordered_end();
 	while(cond_i != cond_end)
@@ -2319,17 +2324,17 @@ bool matches_special_filter(const config* cfg, const vconfig filter)
 		const std::string& cond_name = *((*cond_i).first);
 		const vconfig cond_filter(&(*((*cond_i).second)));
 
-		//handle [and]
+		// Handle [and]
 		if(cond_name == "and")
 		{
 			matches = matches && matches_special_filter(cfg, cond_filter);
 		}
-		//handle [or]
+		// Handle [or]
 		else if(cond_name == "or")
 		{
 			matches = matches || matches_special_filter(cfg, cond_filter);
 		}
-		//handle [not]
+		// Handle [not]
 		else if(cond_name == "not")
 		{
 			matches = matches && !matches_special_filter(cfg, cond_filter);
@@ -2495,18 +2500,18 @@ bool pump()
 
 	while(events_queue.empty() == false) {
 		queued_event ev = events_queue.front();
-		events_queue.pop_front(); //pop now for exception safety
+		events_queue.pop_front(); 	// pop now for exception safety
 		const std::string& event_name = ev.name;
 		typedef std::multimap<std::string,event_handler>::iterator itor;
 
-		// clear the unit cache, since the best clearing time is hard to figure out
-		// due to status changes by WML every event will flush the cache.
+		// Clear the unit cache, since the best clearing time is hard to figure out
+		// due to status changes by WML. Every event will flush the cache.
 		unit::clear_status_caches();
 
-		//find all handlers for this event in the map
+		// Find all handlers for this event in the map
 		std::pair<itor,itor> i = events_map.equal_range(event_name);
 
-		//set the variables for the event
+		// Set the variables for the event
 		if(i.first != i.second && state_of_game != NULL) {
 			char buf[50];
 			snprintf(buf,sizeof(buf),"%d",ev.loc1.x+1);
@@ -2533,7 +2538,7 @@ bool pump()
 		commit_wmi_commands();
 		commit_new_handlers();
 
-		// dialogs can only be shown if the display is not locked
+		// Dialogs can only be shown if the display is not locked
 		if(! screen->video().update_locked()) {
 			show_wml_errors();
 		}
@@ -2564,4 +2569,5 @@ bool entity_location::requires_unit() const
 	return !id_.empty();
 }
 
-} //end namespace game_events
+} // end namespace game_events (2)
+

src/image.cpp

@@ -12,6 +12,9 @@
    See the COPYING file for more details.
 */
 
+//! @file image.cpp 
+//! Routines for images: load, scale, re-color, etc.
+
 #include "global.hpp"
 
 #include "config.hpp"
@@ -39,7 +42,7 @@ typedef std::map<image::locator::value, int> locator_finder_t;
 typedef std::pair<image::locator::value, int> locator_finder_pair;
 locator_finder_t locator_finder;
 
-// Definition of all image maps
+//! Definition of all image maps
 image::image_cache images_,hexed_images_,scaled_to_hex_images_,scaled_to_zoom_,unmasked_images_;
 image::image_cache brightened_images_,semi_brightened_images_;
 
@@ -51,7 +54,7 @@ std::map<surface, surface> reversed_images_;
 
 int red_adjust = 0, green_adjust = 0, blue_adjust = 0;
 
-// list of colors used by the TC image modification
+//! List of colors used by the TC image modification
 std::vector<std::string> team_colors;
 
 std::string image_mask;
@@ -59,10 +62,11 @@ std::string image_mask;
 int zoom = image::tile_size;
 int cached_zoom = 0;
 
-//The "pointer to surfaces" vector is not cleared anymore (the surface are
-//still freed, of course.) I do not think it is a problem, as the number of
-//different surfaces the program may lookup has an upper limit, so its
-//memory usage won't grow indefinitely over time
+// The "pointer to surfaces" vector is not cleared anymore 
+// (the surface are still freed, of course). 
+// I do not think it is a problem, as the number of different surfaces 
+// the program may lookup has an upper limit, so its memory usage 
+// won't grow indefinitely over time.
 template<typename T>
 void reset_cache(std::vector<image::cache_item<T> >& cache)
 {
@@ -74,7 +78,7 @@ void reset_cache(std::vector<image::cache_item<T> >& cache)
 		beg->item = T();
 	}
 }
-}
+} // end anon namespace
 
 namespace image {
 
@@ -323,8 +327,8 @@ surface locator::load_image_sub_file() const
 				}
 				std::string field = *j++;
 
-				if("TC" == function){//deprecated team coloring syntax
-					//replace with proper RC syntax
+				if("TC" == function){ 	// Deprecated team coloring syntax
+					//! @todo replace with proper RC syntax
 					std::string::size_type pos = 0;
 					pos = field.find(',');
 					if (pos == std::string::npos)
@@ -341,7 +345,7 @@ surface locator::load_image_sub_file() const
 					}						
 				}
 
-				if("RC" == function){ //re-color function
+				if("RC" == function){ 	// Re-color function
 					std::vector<std::string> recolor=utils::split(field,'>');
 					if(recolor.size()>1){
 						std::map<Uint32, Uint32> tmp_map;
@@ -357,7 +361,7 @@ surface locator::load_image_sub_file() const
 						}
 					}
 				}									
-				if("FL" == function){ //flip layer
+				if("FL" == function){ 	// Flip layer
 					if(field.empty() || field.find("horiz") != std::string::npos) {
 						xflip = !xflip;
 					}
@@ -465,8 +469,8 @@ void set_team_colors(const std::vector<std::string>& colors)
 void set_image_mask(const std::string& /*image*/)
 {
 
-	//image_mask are blitted in display.cpp
-	//so no need to flush the cache here
+	// image_mask are blitted in display.cpp
+	// so no need to flush the cache here
 /*	
 	if(image_mask != image) {
 		image_mask = image;
@@ -488,9 +492,9 @@ void set_zoom(int amount)
 		reset_cache(semi_brightened_images_);
 		reversed_images_.clear();
 
-		// we keep these caches if:
+		// We keep these caches if:
 		// we use default zoom (it doesn't need those)
-		// or if they are already at the wanted zoom
+		// or if they are already at the wanted zoom.
 		if (zoom != tile_size && zoom != cached_zoom) {
 			reset_cache(scaled_to_zoom_);
 			reset_cache(unmasked_images_);
@@ -501,8 +505,8 @@ void set_zoom(int amount)
 
 static surface get_hexed(const locator i_locator)
 {
-	// we don't want to add it to the unscaled cache
-	// since we will normaly never need the non-hexed one
+	// w.e don't want to add it to the unscaled cache,
+	// since we will normaly never need the non-hexed one.
 	surface image(get_image(i_locator, UNSCALED, false));
 	// Re-cut scaled tiles according to a mask.
 	const surface hex(get_image(game_config::terrain_mask_image,
@@ -512,8 +516,8 @@ static surface get_hexed(const locator i_locator)
 
 static surface get_unmasked(const locator i_locator)
 {
-	// if no scaling needed at this zoom level
-	// we just use the hexed image
+	// If no scaling needed at this zoom level,
+	// we just use the hexed image.
 	surface image(get_image(i_locator, HEXED));
 	if (zoom != tile_size)
 		return scale_surface(image, zoom, zoom);
@@ -549,7 +553,7 @@ static surface get_scaled_to_zoom(const locator i_locator)
 	wassert(tile_size != 0);
 
 	surface res(get_image(i_locator, UNSCALED));
-	// for some reason haloes seems to have invalid images, protect against crashing
+	// For some reason haloes seems to have invalid images, protect against crashing
 	if(!res.null()) {
 		return scale_surface(res, ((res.get()->w * zoom) / tile_size), ((res.get()->h * zoom) / tile_size));
 	} else {
@@ -588,7 +592,7 @@ surface get_image(const image::locator& i_locator, TYPE type, bool add_to_cache
 		imap = &scaled_to_hex_images_;
 		break;
 	case SCALED_TO_ZOOM:
-		// only use separate cache if scaled
+		// Only use separate cache if scaled
 		if(zoom != tile_size) {
 			imap = &scaled_to_zoom_;
 		} else {
@@ -600,7 +604,7 @@ surface get_image(const image::locator& i_locator, TYPE type, bool add_to_cache
 		imap = &hexed_images_;
 		break;
 	case UNMASKED:
-		// only use separate cache if scaled
+		// Only use separate cache if scaled
 		if(zoom != tile_size) {
 			imap = &unmasked_images_;
 		} else {
@@ -620,8 +624,8 @@ surface get_image(const image::locator& i_locator, TYPE type, bool add_to_cache
 	if(i_locator.in_cache(*imap))
 		return i_locator.locate_in_cache(*imap);
 
-	// If type is unscaled, directly load the image from the disk. Else,
-	// create it from the unscaled image
+	// If type is unscaled, directly load the image from the disk. 
+	// Else, create it from the unscaled image.
 	if(is_unscaled) {
 		res = i_locator.load_from_disk();
 
@@ -657,7 +661,7 @@ surface get_image(const image::locator& i_locator, TYPE type, bool add_to_cache
 		}
 	}
 
-	// optimizes surface before storing it
+	// Optimizes surface before storing it
 	res = create_optimized_surface(res);
 	if(add_to_cache) i_locator.add_to_cache(*imap, res);
 	return res;
@@ -692,7 +696,7 @@ bool exists(const image::locator& i_locator)
 	if (type != loc::FILE && type != loc::SUB_FILE)
 		return false;
 
-	// the insertion will fail if there is already an element in the cache
+	// The insertion will fail if there is already an element in the cache
 	std::pair< std::map< image::locator, bool >::iterator, bool >
 		it = image_existance_map.insert(std::make_pair(i_locator, false));
 	bool &cache = it.first->second;
@@ -702,4 +706,5 @@ bool exists(const image::locator& i_locator)
 }
 
 
-}
+} // end namespace image 
+

src/unit_types.cpp

@@ -12,6 +12,9 @@
    See the COPYING file for more details.
 */
 
+//! @file unit_types.cpp 
+//! Handle unit-type specific attributes, animations, advancement.
+
 #include "global.hpp"
 
 #include "game_config.hpp"
@@ -32,12 +35,13 @@
 
 //! The Halbardier got renamed so this function fixes that, all 
 //! functions which assign id_ in unit or unit_types should use 
-//! this wrapper in order to keep compatibility with older versions
+//! this wrapper in order to keep compatibility with older versions.
 //
 // @param id	the id of the unit
 //
-// @returns		the new id of the unit if id == Halbardier it returns
-// 				Halberdier otherwise id unmodified
+// @returns		the new id of the unit.
+// 				if id == Halbardier it returns Halberdier, 
+// 				otherwise id unmodified
 std::string unit_id_test(const std::string& id)
 {
 	if(id == "Halbardier") {
@@ -64,7 +68,8 @@ attack_type::attack_type(const config& cfg,const std::string& id, const std::str
 	}
 
 	if(cfg.child("frame") || cfg.child("missile_frame") || cfg.child("sound")) {
-		LOG_STREAM(err, config) << "the animation for " << cfg["name"] << "in unit " << id << " is directly in the attack, please use [animation]\n" ;
+		LOG_STREAM(err, config) << "the animation for " << cfg["name"] << "in unit " << id 
+								<< " is directly in the attack, please use [animation]\n" ;
 	}
 	if(animation_.empty()) {
 		animation_.push_back(attack_animation(cfg));
@@ -107,7 +112,7 @@ attack_type::attack_type(const config& cfg,const std::string& id, const std::str
 const attack_animation* attack_type::animation(const game_display& disp, const gamemap::location& loc,const unit* my_unit,
 		const fighting_animation::hit_type hit,const attack_type*secondary_attack,int swing_num,int damage) const
 {
-	//select one of the matching animations at random
+	// Select one of the matching animations at random
 	std::vector<const attack_animation*>  options;
 	int max_val = -3;
 	for(std::vector<attack_animation>::const_iterator i = animation_.begin(); i != animation_.end(); ++i) {
@@ -241,7 +246,7 @@ bool attack_type::apply_modification(const config& cfg,std::string* description)
 	return true;
 }
 
-/* same as above, except only update the descriptions */
+// Same as above, except only update the descriptions
 bool attack_type::describe_modification(const config& cfg,std::string* description)
 {
 	if(!matches_filter(cfg,0))
@@ -306,7 +311,7 @@ int unit_movement_type::movement_cost(const gamemap& map,
 		return i->second;
 	}
 
-	//if this is an alias, then select the best of all underlying terrains
+	// If this is an alias, then select the best of all underlying terrains.
 	const t_translation::t_list& underlying = map.underlying_mvt_terrain(terrain);
 	if(underlying.size() != 1 || underlying.front() != terrain) {
 		bool revert = (underlying.front() == t_translation::MINUS ? true : false);
@@ -382,7 +387,7 @@ int unit_movement_type::defense_modifier(const gamemap& map,
 		return i->second;
 	}
 
-	//if this is an alias, then select the best of all underlying terrains
+	// If this is an alias, then select the best of all underlying terrains.
 	const t_translation::t_list& underlying = 
 		map.underlying_def_terrain(terrain);
 
@@ -529,9 +534,11 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 			config nvar_cfg(cfg);
 			nvar_cfg.merge_with(var_cfg);
 			nvar_cfg.clear_children("variation");
-			variations_.insert(std::pair<std::string,unit_type*>(nvar_cfg["variation_name"],new unit_type(nvar_cfg,mv_types,races,traits)));
+			variations_.insert(std::pair<std::string,unit_type*>(nvar_cfg["variation_name"],
+												 new unit_type(nvar_cfg,mv_types,races,traits)));
 		} else {
-			variations_.insert(std::pair<std::string,unit_type*>((**var)["variation_name"],new unit_type(**var,mv_types,races,traits)));
+			variations_.insert(std::pair<std::string,unit_type*>((**var)["variation_name"],
+												 new unit_type(**var,mv_types,races,traits)));
 		}
 	}
 
@@ -609,7 +616,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		race_ = &dummy_race;
 	}
 
-	//insert any traits that are just for this unit type
+	// Insert any traits that are just for this unit type
 	const config::child_list& unit_traits = cfg.get_children("trait");
 	possibleTraits_.insert(possibleTraits_.end(),unit_traits.begin(),unit_traits.end());
 
@@ -686,7 +693,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"standing animations  are deprecate, support will be removed in 1.3.8 (in unit "<<id()<<")\n";
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=standing flag\n";
 	}
-	// always have a standing animation
+	// Always have a standing animation
 	animations_.push_back(unit_animation(0,unit_frame(image(),0),"standing",-1));
 	expanded_cfg = unit_animation::prepare_animation(cfg,"idle_anim");
 	const config::child_list& idle_anims = expanded_cfg.get_children("idle_anim");
@@ -696,7 +703,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"idling animations  are deprecate, support will be removed in 1.3.8 (in unit "<<id()<<")\n";
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=idling flag\n";
 	}
-	//idle anims can be empty
+	// Idle anims can be empty
 	expanded_cfg = unit_animation::prepare_animation(cfg,"levelin_anim");
 	const config::child_list& levelin_anims = expanded_cfg.get_children("levelin_anim");
 	for(config::child_list::const_iterator levelin_anim = levelin_anims.begin(); levelin_anim != levelin_anims.end(); ++levelin_anim) {
@@ -706,7 +713,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=levelin flag\n";
 	}
 	animations_.push_back(unit_animation(0,unit_frame(image(),600,"1.0","",display::rgb(255,255,255),"1~0:600"),"levelin",-1));
-	// always have a levelin animation
+	// Always have a levelin animation
 	expanded_cfg = unit_animation::prepare_animation(cfg,"levelout_anim");
 	const config::child_list& levelout_anims = expanded_cfg.get_children("levelout_anim");
 	for(config::child_list::const_iterator levelout_anim = levelout_anims.begin(); levelout_anim != levelout_anims.end(); ++levelout_anim) {
@@ -716,7 +723,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=levelout flag\n";
 	}
 	animations_.push_back(unit_animation(0,unit_frame(image(),600,"1.0","",display::rgb(255,255,255),"0~1:600"),"levelin",-1));
-	// always have a levelout animation
+	// Always have a levelout animation
 	expanded_cfg = unit_animation::prepare_animation(cfg,"healing_anim");
 	const config::child_list& healing_anims = expanded_cfg.get_children("healing_anim");
 	for(config::child_list::const_iterator healing_anim = healing_anims.begin(); healing_anim != healing_anims.end(); ++healing_anim) {
@@ -727,7 +734,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=healing flag\n";
 	}
 	animations_.push_back(unit_animation(0,unit_frame(image(),500),"healing",-1));
-	// always have a healing animation
+	// Always have a healing animation
 	expanded_cfg = unit_animation::prepare_animation(cfg,"healed_anim");
 	const config::child_list& healed_anims = expanded_cfg.get_children("healed_anim");
 	for(config::child_list::const_iterator healed_anim = healed_anims.begin(); healed_anim != healed_anims.end(); ++healed_anim) {
@@ -738,7 +745,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=healed flag\n";
 	}
 	animations_.push_back(unit_animation(0,unit_frame(image(),240,"1.0","",display::rgb(255,255,255),"0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30"),"healed",-1));
-	// always have a healed animation
+	// Always have a healed animation
 	expanded_cfg = unit_animation::prepare_animation(cfg,"poison_anim");
 	const config::child_list& poison_anims = expanded_cfg.get_children("poison_anim");
 	for(config::child_list::const_iterator poison_anim = poison_anims.begin(); poison_anim != poison_anims.end(); ++poison_anim) {
@@ -749,9 +756,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 		//lg::wml_error<<"please put it with an [animation] tag and apply_to=poison flag\n";
 	}
 	animations_.push_back(unit_animation(0,unit_frame(image(),240,"1.0","",display::rgb(0,255,0),"0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30"),"poison",-1));
-	// always have a poison animation
-
-
+	// Always have a poison animation 
 
 
 
@@ -762,7 +767,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 	}
 	if(defensive_animations_.empty()) {
 		defensive_animations_.push_back(defensive_animation(-150,unit_frame(image(),300)));
-		// always have a defensive animation
+		// Always have a defensive animation
 	}
 
 	expanded_cfg = unit_animation::prepare_animation(cfg,"teleport_anim");
@@ -772,7 +777,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 	}
 	if(teleport_animations_.empty()) {
 		teleport_animations_.push_back(unit_animation(-20,unit_frame(image(),40)));
-		// always have a defensive animation
+		// Always have a defensive animation
 	}
 	expanded_cfg = unit_animation::prepare_animation(cfg,"extra_anim");
 	const config::child_list& extra_anims = expanded_cfg.get_children("extra_anim");
@@ -789,7 +794,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 	}
 	if(death_animations_.empty()) {
 		death_animations_.push_back(death_animation(0,unit_frame(image(),10)));
-		// always have a defensive animation
+		// Always have a defensive animation
 	}
 
 	expanded_cfg = unit_animation::prepare_animation(cfg,"movement_anim");
@@ -799,7 +804,7 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 	}
 	if(movement_animations_.empty()) {
 		movement_animations_.push_back(movement_animation(0,unit_frame(image(),150)));
-		// always have a movement animation
+		// Always have a movement animation
 	}
 
 
@@ -810,11 +815,11 @@ unit_type::unit_type(const config& cfg, const movement_type_map& mv_types,
 	}
 	if(victory_animations_.empty()) {
 		victory_animations_.push_back(victory_animation(0,unit_frame(image(),1)));
-		// always have a victory animation
+		// Always have a victory animation
 	}
 	flag_rgb_ = cfg["flag_rgb"];
 	game_config::add_color_info(cfg);
-	// deprecation messages, only seen when unit is parsed for the first time
+	// Deprecation messages, only seen when unit is parsed for the first time.
 
 	hide_help_= cfg_["hide_help"] == "true" ? true : false;
 }
@@ -855,7 +860,7 @@ const std::string& unit_type::id() const
 		id_ = unit_id_test(cfg_["id"]);
 
 		if(id_.empty()) {
-			// this code is only for compatibility with old unit defs and savefiles
+			// This code is only for compatibility with old unit defs and savefiles.
 			id_ = unit_id_test(cfg_["name"]);
 		}
 
@@ -1013,12 +1018,12 @@ void unit_type::add_advancement(const unit_type &to_unit,int xp)
 	const std::string &to_id =  to_unit.cfg_["id"];
 	const std::string &from_id =  cfg_["id"];
 
-	// add extra advancement path to this unit type
+	// Add extra advancement path to this unit type
 	lg::info(lg::config) << "adding advancement from " << from_id << " to " << to_id << "\n";
 	advances_to_.push_back(to_id);
 	if(xp>0 && experience_needed_>xp) experience_needed_=xp;
 
-	// add advancements to gendered subtypes, if supported by to_unit
+	// Add advancements to gendered subtypes, if supported by to_unit
 	for(int gender=0; gender<=1; ++gender) {
 		if(gender_types_[gender] == NULL) continue;
 		if(to_unit.gender_types_[gender] == NULL) {
@@ -1029,10 +1034,10 @@ void unit_type::add_advancement(const unit_type &to_unit,int xp)
 		gender_types_[gender]->add_advancement(*(to_unit.gender_types_[gender]),xp);
 	}
 
-	// add advancements to variation subtypes
-	// since these are still a rare and special-purpose feature,
+	// Add advancements to variation subtypes.
+	// Since these are still a rare and special-purpose feature,
 	// we assume that the unit designer knows what they're doing,
-	// and don't block advancements that would remove a variation
+	// and don't block advancements that would remove a variation.
 	for(variations_map::iterator v=variations_.begin();
 	    v!=variations_.end(); ++v) {
 		lg::info(lg::config) << "variation advancement: ";
@@ -1080,7 +1085,7 @@ void game_data::set_config(const config& cfg)
 		}
 		else 
 		{
-			//LOAD UNIT TYPES
+			// LOAD UNIT TYPES
 			const unit_type u_type(**i.first,movement_types,races,unit_traits);
 			unit_types.insert(std::pair<std::string,unit_type>(u_type.id(),u_type));
 			increment_set_config_progress();
@@ -1099,7 +1104,7 @@ void game_data::set_config(const config& cfg)
 				unit_type_map::iterator from_unit = unit_types.find(based_from);
 				if(from_unit != unit_types.end())
 				{
-					//derive a new unit type from an existing base unit id
+					// Derive a new unit type from an existing base unit id
 					config merge_cfg(from_unit->second.cfg_);
 					merge_cfg.merge_with(**i.first);
 					merge_cfg.clear_children("base_unit");
@@ -1118,7 +1123,7 @@ void game_data::set_config(const config& cfg)
 				}
 			}
 		}
-		//if we iterate through the whole list and no work was done, an error has occurred
+		// If we iterate through the whole list and no work was done, an error has occurred
 		if(new_count >= base_unit_count)
 		{
 			lg::warn(lg::config) << "unknown unit(s) " << skipped
@@ -1131,7 +1136,7 @@ void game_data::set_config(const config& cfg)
 		}
 	}
 	
-	// fix up advance_from references
+	// Fix up advance_from references
 	for(i = cfg.child_range("unit"); i.first != i.second; ++i.first)
 	{
 		config::const_child_itors af;