(svn r19136) -Doc: Added Doxygen comments for industry checking procedures.

2 files changed, 65 insertions, 21 deletions

diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
index f0ebf4d18..5ec1d150b 100644
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -1136,11 +1136,19 @@ void OnTick_Industry()
 	}
 }
 
+/** Check the conditions of #CHECK_NOTHING.
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_NULL(TileIndex tile)
 {
 	return true;
 }
 
+/** Check the conditions of #CHECK_FOREST (Industry should be build above snow-line in arctic climate).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_Forest(TileIndex tile)
 {
 	if (_settings_game.game_creation.landscape == LT_ARCTIC) {
@@ -1152,6 +1160,10 @@ static bool CheckNewIndustry_Forest(TileIndex tile)
 	return true;
 }
 
+/** Check the conditions of #CHECK_REFINERY (Industry should be positioned near edge of the map).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_OilRefinery(TileIndex tile)
 {
 	if (_game_mode == GM_EDITOR) return true;
@@ -1163,6 +1175,10 @@ static bool CheckNewIndustry_OilRefinery(TileIndex tile)
 
 extern bool _ignore_restrictions;
 
+/** Check the conditions of #CHECK_OIL_RIG (Industries at sea should be positioned near edge of the map).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_OilRig(TileIndex tile)
 {
 	if (_game_mode == GM_EDITOR && _ignore_restrictions) return true;
@@ -1173,6 +1189,10 @@ static bool CheckNewIndustry_OilRig(TileIndex tile)
 	return false;
 }
 
+/** Check the conditions of #CHECK_FARM (Industry should be below snow-line in arctic).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_Farm(TileIndex tile)
 {
 	if (_settings_game.game_creation.landscape == LT_ARCTIC) {
@@ -1184,6 +1204,10 @@ static bool CheckNewIndustry_Farm(TileIndex tile)
 	return true;
 }
 
+/** Check the conditions of #CHECK_PLANTATION (Industry should NOT be in the desert).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_Plantation(TileIndex tile)
 {
 	if (GetTropicZone(tile) == TROPICZONE_DESERT) {
@@ -1194,6 +1218,10 @@ static bool CheckNewIndustry_Plantation(TileIndex tile)
 	return true;
 }
 
+/** Check the conditions of #CHECK_WATER (Industry should be in the desert).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_Water(TileIndex tile)
 {
 	if (GetTropicZone(tile) != TROPICZONE_DESERT) {
@@ -1204,6 +1232,10 @@ static bool CheckNewIndustry_Water(TileIndex tile)
 	return true;
 }
 
+/** Check the conditions of #CHECK_LUMBERMILL (Industry should be in the rain forest).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_Lumbermill(TileIndex tile)
 {
 	if (GetTropicZone(tile) != TROPICZONE_RAINFOREST) {
@@ -1213,22 +1245,32 @@ static bool CheckNewIndustry_Lumbermill(TileIndex tile)
 	return true;
 }
 
+/** Check the conditions of #CHECK_BUBBLEGEN (Industry should be in low land).
+ * @param tile %Tile to perform the checking.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 static bool CheckNewIndustry_BubbleGen(TileIndex tile)
 {
 	return GetTileZ(tile) <= TILE_HEIGHT * 4;
 }
 
+/** Industrytype check function signature.
+ * @param tile %Tile to check.
+ * @return \c true if industry may be build, \c false otherwise.
+ */
 typedef bool CheckNewIndustryProc(TileIndex tile);
+
+/** Check functions for different types of industry. */
 static CheckNewIndustryProc * const _check_new_industry_procs[CHECK_END] = {
-	CheckNewIndustry_NULL,
-	CheckNewIndustry_Forest,
-	CheckNewIndustry_OilRefinery,
-	CheckNewIndustry_Farm,
-	CheckNewIndustry_Plantation,
-	CheckNewIndustry_Water,
-	CheckNewIndustry_Lumbermill,
-	CheckNewIndustry_BubbleGen,
-	CheckNewIndustry_OilRig
+	CheckNewIndustry_NULL,        ///< CHECK_NOTHING
+	CheckNewIndustry_Forest,      ///< CHECK_FOREST
+	CheckNewIndustry_OilRefinery, ///< CHECK_REFINERY
+	CheckNewIndustry_Farm,        ///< CHECK_FARM
+	CheckNewIndustry_Plantation,  ///< CHECK_PLANTATION
+	CheckNewIndustry_Water,       ///< CHECK_WATER
+	CheckNewIndustry_Lumbermill,  ///< CHECK_LUMBERMILL
+	CheckNewIndustry_BubbleGen,   ///< CHECK_BUBBLEGEN
+	CheckNewIndustry_OilRig,      ///< CHECK_OIL_RIG
 };
 
 static const Town *CheckMultipleIndustryInTown(TileIndex tile, int type)
diff --git a/src/industrytype.h b/src/industrytype.h
index 294d10623..6ee5101e6 100644
--- a/src/industrytype.h
+++ b/src/industrytype.h
@@ -25,6 +25,7 @@ enum {
 	CLEAN_TILELAYOUT,      ///< Free the dynamically allocated tile layout structure
 };
 
+/** Available types of industry lifetimes. */
 enum IndustryLifeType {
 	INDUSTRYLIFE_BLACK_HOLE =      0, ///< Like power plants and banks
 	INDUSTRYLIFE_EXTRACTIVE = 1 << 0, ///< Like mines
@@ -32,19 +33,20 @@ enum IndustryLifeType {
 	INDUSTRYLIFE_PROCESSING = 1 << 2, ///< Like factories
 };
 
-/* Procedures that can be run to check whether an industry may
- * build at location the given to the procedure */
+/** Available procedures to check whether an industry may build at a given location.
+ * @see CheckNewIndustryProc, _check_new_industry_procs[]
+ */
 enum CheckProc {
-	CHECK_NOTHING,
-	CHECK_FOREST,
-	CHECK_REFINERY,
-	CHECK_FARM,
-	CHECK_PLANTATION,
-	CHECK_WATER,
-	CHECK_LUMBERMILL,
-	CHECK_BUBBLEGEN,
-	CHECK_OIL_RIG,
-	CHECK_END,
+	CHECK_NOTHING,    ///< Always succeeds.
+	CHECK_FOREST,     ///< %Industry should be build above snow-line in arctic climate.
+	CHECK_REFINERY,   ///< %Industry should be positioned near edge of the map.
+	CHECK_FARM,       ///< %Industry should be below snow-line in arctic.
+	CHECK_PLANTATION, ///< %Industry should NOT be in the desert.
+	CHECK_WATER,      ///< %Industry should be in the desert.
+	CHECK_LUMBERMILL, ///< %Industry should be in the rain forest.
+	CHECK_BUBBLEGEN,  ///< %Industry should be in low land.
+	CHECK_OIL_RIG,    ///< Industries at sea should be positioned near edge of the map.
+	CHECK_END,        ///< End marker of the industry check procedures.
 };
 
 /** How was the industry created */