--- a/src/industry.h
+++ b/src/industry.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file industry.h */
+
 #ifndef INDUSTRY_H
 #define INDUSTRY_H
 
@@ -18,30 +20,33 @@
 	INDUSTRYLIFE_CLOSABLE,         ///< Industry can only close (no production change)
 } IndustryLifeType;
 
+/**
+ * Defines the internal data of a functionnal industry
+ */
 struct Industry {
-	TileIndex xy;
-	byte width; /* swapped order of w/h with town */
+	TileIndex xy;                   ///< coordinates of the primary tile the industry is built one
+	byte width;
 	byte height;
-	const Town* town;
-	CargoID produced_cargo[2];
-	uint16 cargo_waiting[2];
-	byte production_rate[2];
-	CargoID accepts_cargo[3];
-	byte prod_level;
-	uint16 last_mo_production[2];
-	uint16 last_mo_transported[2];
-	byte pct_transported[2];
-	uint16 total_production[2];
-	uint16 total_transported[2];
-	uint16 counter;
+	const Town* town;               ///< Nearest town
+	CargoID produced_cargo[2];      ///< 2 production cargo slots
+	uint16 cargo_waiting[2];        ///< amount of cargo produced per cargo
+	byte production_rate[2];        ///< production rate for each cargo
+	CargoID accepts_cargo[3];       ///< 3 input cargo slots
+	byte prod_level;                ///< general production level
+	uint16 last_mo_production[2];   ///< stats of last month production per cargo
+	uint16 last_mo_transported[2];  ///< stats of last month transport per cargo
+	byte pct_transported[2];        ///< percentage transported per cargo
+	uint16 total_production[2];     ///< total units produced per cargo
+	uint16 total_transported[2];    ///< total units transported per cargo
+	uint16 counter;                 ///< used for animation and/or production (if available cargo)
 
-	byte type;
-	OwnerByte owner;
-	byte random_color;
-	Year last_prod_year;
-	byte was_cargo_delivered;
+	byte type;                      ///< type of industry. see IT_COAL_MINE and others
+	OwnerByte owner;                ///< owner of the industry.  Which SHOULD always be (imho) OWNER_NONE
+	byte random_color;              ///< randomized colour of the industry, for display purpose
+	Year last_prod_year;            ///< last year of production
+	byte was_cargo_delivered;       ///< flag that indicate this has been the closest industry chosen for cargo delivery by a station. see DeliverGoodsToIndustry
 
-	IndustryID index;
+	IndustryID index;               ///< index of the industry in the pool of industries
 };
 
 typedef struct IndustryTileTable {
@@ -49,59 +54,62 @@
 	IndustryGfx gfx;
 } IndustryTileTable;
 
+/**
+ * Defines the data structure for constructing industry.
+ */
 typedef struct IndustrySpec {
-	/** Tables with the 'layout' of different composition of GFXes */
-	const IndustryTileTable *const *table;
-	/** Number of elements in the table */
-	byte num_table;
-	/** Base cost multiplier*/
-	byte cost_multiplier;
-	/** Industries this industry cannot be close to */
-	IndustryType conflicting[3];
-	/** index to a procedure to check for conflicting circumstances */
-	byte check_proc;
-
+	const IndustryTileTable *const *table;///< List of the tiles composing the industry
+	byte num_table;                       ///< Number of elements in the table
+	byte cost_multiplier;                 ///< Base cost multiplier*/
+	IndustryType conflicting[3];          ///< Industries this industry cannot be close to
+	byte check_proc;                      ///< Index to a procedure to check for conflicting circumstances
 	CargoID produced_cargo[2];
 	byte production_rate[2];
-	/** The minimum amount of cargo transported to the stations; if the
-	 * waiting cargo is less than this number, no cargo is moved to it*/
-	byte minimal_cargo;
-	CargoID accepts_cargo[3];
-
-	IndustryLifeType life_type;  ///< This is also known as Industry production flag, in newgrf specs
-
-	byte climate_availability;  ///< Bitmask, giving landscape enums as bit position
-
-	StringID name;
-	StringID closure_text;
-	StringID production_up_text;
-	StringID production_down_text;
+	byte minimal_cargo;                   ///< minimum amount of cargo transported to the stations
+	                                      ///< If the waiting cargo is less than this number, no cargo is moved to it
+	CargoID accepts_cargo[3];             ///< 3 accepted cargos
+	IndustryLifeType life_type;           ///< This is also known as Industry production flag, in newgrf specs
+	byte climate_availability;            ///< Bitmask, giving landscape enums as bit position
+	StringID name;                        ///< Displayed name of the industry
+	StringID closure_text;                ///< Message appearing when the industry closes
+	StringID production_up_text;          ///< Message appearing when the industry's production is increasing
+	StringID production_down_text;        ///< Message appearing when the industry's production is decreasing
 } IndustrySpec;
 
+/**
+ * Defines the data structure of each indivudual tile of an industry.
+ */
 typedef struct IndustryTileSpec {
-	CargoID accepts_cargo[3];
-	Slope slopes_refused;
+	CargoID accepts_cargo[3];             ///< Cargo accepted by this tile
+	Slope slopes_refused;                 ///< slope pattern on which this tile cannot be built
 } IndustryTileSpec;
 
-const IndustrySpec *GetIndustrySpec(IndustryType thistype);
-const IndustryTileSpec *GetIndustryTileSpec(IndustryGfx gfx);
+const IndustrySpec *GetIndustrySpec(IndustryType thistype);    ///< Array of industries default data
+const IndustryTileSpec *GetIndustryTileSpec(IndustryGfx gfx);  ///< Array of industry tiles default data
 
 DECLARE_OLD_POOL(Industry, Industry, 3, 8000)
 
 /**
  * Check if an Industry really exists.
+ * @param industry to check
+ * @return true if position is a valid one
  */
 static inline bool IsValidIndustry(const Industry *industry)
 {
 	return industry->xy != 0;
 }
 
+/**
+ * Check if an Industry exists whithin the pool of industries
+ * @param index of the desired industry
+ * @return true if it is inside the pool
+ */
 static inline bool IsValidIndustryID(IndustryID index)
 {
 	return index < GetIndustryPoolSize() && IsValidIndustry(GetIndustry(index));
 }
 
-VARDEF int _total_industries;
+VARDEF int _total_industries; //general counter
 
 static inline IndustryID GetMaxIndustryIndex(void)
 {