(svn r9558) -Documentation: doxygen and comment changes: 'T' now. Almost done

1 files changed, 39 insertions, 30 deletions

diff --git a/src/town.h b/src/town.h
index e824d3fe6..832fd913b 100644
--- a/src/town.h
+++ b/src/town.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file town.h */
+
 #ifndef TOWN_H
 #define TOWN_H
 
@@ -76,34 +78,34 @@ struct BuildingCounts {
 struct Town {
 	TileIndex xy;
 
-	// Current population of people and amount of houses.
+	/* Current population of people and amount of houses. */
 	uint16 num_houses;
 	uint32 population;
 
-	// Town name
+	/* Town name */
 	uint16 townnametype;
 	uint32 townnameparts;
 
-	// NOSAVE: Location of name sign, UpdateTownVirtCoord updates this.
+	/* NOSAVE: Location of name sign, UpdateTownVirtCoord updates this. */
 	ViewportSign sign;
 
-	// Makes sure we don't build certain house types twice.
-	// bit 0 = Building funds received
-	// bit 1 = CHURCH
-	// bit 2 = STADIUM
+	/* Makes sure we don't build certain house types twice.
+	 * bit 0 = Building funds received
+	 * bit 1 = CHURCH
+	 * bit 2 = STADIUM */
 	byte flags12;
 
-	// Which players have a statue?
+	/* Which players have a statue? */
 	byte statues;
 
-	// Player ratings as well as a mask that determines which players have a rating.
+	/* Player ratings as well as a mask that determines which players have a rating. */
 	byte have_ratings;
-	uint8 unwanted[MAX_PLAYERS]; // how many months companies aren't wanted by towns (bribe)
-	PlayerByte exclusivity;        // which player has exslusivity
-	uint8 exclusive_counter;     // months till the exclusivity expires
+	uint8 unwanted[MAX_PLAYERS]; ///< how many months companies aren't wanted by towns (bribe)
+	PlayerByte exclusivity;      ///< which player has exslusivity
+	uint8 exclusive_counter;     ///< months till the exclusivity expires
 	int16 ratings[MAX_PLAYERS];
 
-	// Maximum amount of passengers and mail that can be transported.
+	/* Maximum amount of passengers and mail that can be transported. */
 	uint32 max_pass;
 	uint32 max_mail;
 	uint32 new_max_pass;
@@ -113,36 +115,36 @@ struct Town {
 	uint32 new_act_pass;
 	uint32 new_act_mail;
 
-	// Amount of passengers that were transported.
+	/* Amount of passengers that were transported. */
 	byte pct_pass_transported;
 	byte pct_mail_transported;
 
-	// Amount of food and paper that was transported. Actually a bit mask would be enough.
+	/* Amount of food and paper that was transported. Actually a bit mask would be enough. */
 	uint16 act_food;
 	uint16 act_water;
 	uint16 new_act_food;
 	uint16 new_act_water;
 
-	// Time until we rebuild a house.
+	/* Time until we rebuild a house. */
 	byte time_until_rebuild;
 
-	// When to grow town next time.
+	/* When to grow town next time. */
 	byte grow_counter;
 	byte growth_rate;
 
-	// Fund buildings program in action?
+	/* Fund buildings program in action? */
 	byte fund_buildings_months;
 
-	// Fund road reconstruction in action?
+	/* Fund road reconstruction in action? */
 	byte road_build_months;
 
-	// Index in town array
+	/* Index in town array */
 	TownID index;
 
-	// NOSAVE: UpdateTownRadius updates this given the house count.
+	/* NOSAVE: UpdateTownRadius updates this given the house count. */
 	uint16 radius[5];
 
-	// NOSAVE: The number of each type of building in the town.
+	/* NOSAVE: The number of each type of building in the town. */
 	BuildingCounts building_counts;
 };
 
@@ -197,8 +199,8 @@ enum {
 };
 
 enum {
-	// These refer to the maximums, so Appalling is -1000 to -400
-	// MAXIMUM RATINGS BOUNDARIES
+	/* These refer to the maximums, so Appalling is -1000 to -400
+	 * MAXIMUM RATINGS BOUNDARIES */
 	RATING_MINIMUM     = -1000,
 	RATING_APPALLING   =  -400,
 	RATING_VERYPOOR    =  -200,
@@ -207,11 +209,11 @@ enum {
 	RATING_GOOD        =   400,
 	RATING_VERYGOOD    =   600,
 	RATING_EXCELLENT   =   800,
-	RATING_OUTSTANDING =  1000,         // OUTSTANDING
+	RATING_OUTSTANDING =  1000,         ///< OUTSTANDING
 
 	RATING_MAXIMUM = RATING_OUTSTANDING,
 
-	// RATINGS AFFECTING NUMBERS
+	/* RATINGS AFFECTING NUMBERS */
 	RATING_TREE_DOWN_STEP = -35,
 	RATING_TREE_MINIMUM   = RATING_MINIMUM,
 	RATING_TREE_UP_STEP   = 7,
@@ -241,16 +243,16 @@ enum {
 	TOWN_HOUSE_COMPLETED  =  3,
 };
 
-/* This enum is used in conjonction with town->flags12.
+/** This enum is used in conjonction with town->flags12.
  * IT simply states what bit is used for.
  * It is pretty unrealistic (IMHO) to only have one church/stadium
  * per town, NO MATTER the population of it.
  * And there are 5 more bits available on flags12...
  */
 enum {
-	TOWN_IS_FUNDED      = 0,   // Town has received some funds for
-	TOWN_HAS_CHURCH     = 1,   // There can be only one church by town.
-	TOWN_HAS_STADIUM    = 2    // There can be only one stadium by town.
+	TOWN_IS_FUNDED      = 0,   ///< Town has received some funds for
+	TOWN_HAS_CHURCH     = 1,   ///< There can be only one church by town.
+	TOWN_HAS_STADIUM    = 2    ///< There can be only one stadium by town.
 };
 
 bool CheckforTownRating(uint32 flags, Town *t, byte type);
@@ -267,12 +269,19 @@ static inline HouseSpec *GetHouseSpecs(HouseID house_id)
 
 /**
  * Check if a Town really exists.
+ * @param town to inquiry
+ * @return true if it exists
  */
 static inline bool IsValidTown(const Town* town)
 {
 	return town->xy != 0;
 }
 
+/**
+ * Check if a TownID is valid.
+ * @param TownID to inquiry
+ * @return true if it exists
+ */
 static inline bool IsValidTownID(TownID index)
 {
 	return index < GetTownPoolSize() && IsValidTown(GetTown(index));