(svn r22413) -Document: even more stuff

15 files changed, 78 insertions, 6 deletions

diff --git a/src/airport.cpp b/src/airport.cpp
index 2173da9ed..389cbe2b8 100644
--- a/src/airport.cpp
+++ b/src/airport.cpp
@@ -16,6 +16,14 @@
 #include "table/airporttile_ids.h"
 
 
+/**
+ * Define a generic airport.
+ * @param name Suffix of the names of the airport data.
+ * @param terminals The terminals.
+ * @param num_helipads Number of heli pads.
+ * @param flags Information about the class of FTA.
+ * @param delta_z Height of the arport above the land.
+ */
 #define AIRPORT_GENERIC(name, terminals, num_helipads, flags, delta_z) \
 	static AirportFTAClass _airportfta_ ## name(_airport_moving_data_ ## name, terminals, \
 			num_helipads, _airport_entries_ ## name, flags, _airport_fta_ ## name, delta_z);
@@ -154,7 +162,12 @@ static uint16 AirportGetNofElements(const AirportFTAbuildup *apFA)
 	return nofelements;
 }
 
-
+/**
+ * Construct the FTA given a description.
+ * @param nofelements The number of elements in the FTA.
+ * @param apFA The description of the FTA.
+ * @return The FTA describing the airport.
+ */
 static AirportFTA *AirportBuildAutomata(uint nofelements, const AirportFTAbuildup *apFA)
 {
 	AirportFTA *FAutomata = MallocT<AirportFTA>(nofelements);
diff --git a/src/articulated_vehicles.cpp b/src/articulated_vehicles.cpp
index 0ef4d9bc4..2350dcb92 100644
--- a/src/articulated_vehicles.cpp
+++ b/src/articulated_vehicles.cpp
@@ -40,6 +40,12 @@ static EngineID GetNextArticulatedPart(uint index, EngineID front_type, Vehicle
 	return GetNewEngineID(GetEngineGRF(front_type), Engine::Get(front_type)->type, GB(callback, 0, 7));
 }
 
+/**
+ * Count the number of articulated parts of an engine.
+ * @param engine_type The engine to get the number of parts of.
+ * @param purchase_window Whether we are in the scope of the purchase window or not, i.e. whether we cannot allocate vehicles.
+ * @return The nmumber of parts.
+ */
 uint CountArticulatedParts(EngineID engine_type, bool purchase_window)
 {
 	if (!HasBit(EngInfo(engine_type)->callback_mask, CBM_VEHICLE_ARTIC_ENGINE)) return 0;
@@ -101,6 +107,11 @@ static inline uint32 GetAvailableVehicleCargoTypes(EngineID engine, bool include
 	return cargos;
 }
 
+/**
+ * Get the capacity of the parts of a given engine.
+ * @param engine The engine to get the capacities from.
+ * @return The cargo capacities.
+ */
 CargoArray GetCapacityOfArticulatedParts(EngineID engine)
 {
 	CargoArray capacity;
@@ -276,6 +287,10 @@ void CheckConsistencyOfArticulatedVehicle(const Vehicle *v)
 	}
 }
 
+/**
+ * Add the remaining articulated parts to the given vehicle.
+ * @param first The head of the articulated bit.
+ */
 void AddArticulatedParts(Vehicle *first)
 {
 	VehicleType type = first->type;
diff --git a/src/autoreplace.cpp b/src/autoreplace.cpp
index 4a7dfcd01..aed2c0e82 100644
--- a/src/autoreplace.cpp
+++ b/src/autoreplace.cpp
@@ -15,6 +15,7 @@
 #include "autoreplace_base.h"
 #include "core/pool_func.hpp"
 
+/** The pool of autoreplace "orders". */
 EngineRenewPool _enginerenew_pool("EngineRenew");
 INSTANTIATE_POOL_METHODS(EngineRenew)
 
diff --git a/src/autoreplace_gui.cpp b/src/autoreplace_gui.cpp
index 86a84fec7..e95606494 100644
--- a/src/autoreplace_gui.cpp
+++ b/src/autoreplace_gui.cpp
@@ -579,6 +579,11 @@ static const WindowDesc _replace_vehicle_desc(
 	_nested_replace_vehicle_widgets, lengthof(_nested_replace_vehicle_widgets)
 );
 
+/**
+ * Show the autoreplace configuration window for a particular group.
+ * @param id_g The group to replace the vehicles for.
+ * @param vehicletype The type of vehicles in the group.
+ */
 void ShowReplaceGroupVehicleWindow(GroupID id_g, VehicleType vehicletype)
 {
 	DeleteWindowById(WC_REPLACE_VEHICLE, vehicletype);
diff --git a/src/base_media_func.h b/src/base_media_func.h
index 69eaccf5f..6adf397c4 100644
--- a/src/base_media_func.h
+++ b/src/base_media_func.h
@@ -274,6 +274,12 @@ template <class Tbase_set>
 #if defined(ENABLE_NETWORK)
 #include "network/network_content.h"
 
+/**
+ * Check whether there's a base set matching some information.
+ * @param ci The content info to compare it to.
+ * @param md5sum Should the MD5 checksum be tested as well?
+ * @param s The list with sets.
+ */
 template <class Tbase_set> bool HasBaseSet(const ContentInfo *ci, bool md5sum, const Tbase_set *s)
 {
 	for (; s != NULL; s = s->next) {
diff --git a/src/bridge.h b/src/bridge.h
index 521c3f128..badf045e3 100644
--- a/src/bridge.h
+++ b/src/bridge.h
@@ -59,6 +59,11 @@ extern BridgeSpec _bridge[MAX_BRIDGES];
 Foundation GetBridgeFoundation(Slope tileh, Axis axis);
 bool HasBridgeFlatRamp(Slope tileh, Axis axis);
 
+/**
+ * Get the specification of a bridge type.
+ * @param i The type of bridge to get the specification for.
+ * @return The specification.
+ */
 static inline const BridgeSpec *GetBridgeSpec(BridgeType i)
 {
 	assert(i < lengthof(_bridge));
diff --git a/src/cargo_type.h b/src/cargo_type.h
index d2261c037..2ca29d203 100644
--- a/src/cargo_type.h
+++ b/src/cargo_type.h
@@ -113,7 +113,7 @@ enum SourceType {
 	ST_TOWN,         ///< Source/destination is a town
 	ST_HEADQUARTERS, ///< Source/destination are company headquarters
 };
-typedef SimpleTinyEnumT<SourceType, byte> SourceTypeByte;
+typedef SimpleTinyEnumT<SourceType, byte> SourceTypeByte; ///< The SourceType packed into a byte for savegame purposes.
 
 typedef uint16 SourceID; ///< Contains either industry ID, town ID or company ID (or INVALID_SOURCE)
 static const SourceID INVALID_SOURCE = 0xFFFF; ///< Invalid/unknown index of source
diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp
index 55c62cd02..2c93d8c85 100644
--- a/src/cargopacket.cpp
+++ b/src/cargopacket.cpp
@@ -246,7 +246,7 @@ void CargoList<Tinst>::Truncate(uint max_remaining)
  *  - MTA_TRANSFER:       Just move without side effects.
  *  - MTA_UNLOAD:         Just move without side effects.
  * @param dest  Destination to move the cargo to.
- * @param count Amount of cargo entities to move.
+ * @param max_move Amount of cargo entities to move.
  * @param mta   How to handle the moving (side effects).
  * @param data  Depending on mta the data of this variable differs:
  *              - MTA_FINAL_DELIVERY - Station ID of packet's origin not to remove.
diff --git a/src/cheat.cpp b/src/cheat.cpp
index a0df14982..f8dae235f 100644
--- a/src/cheat.cpp
+++ b/src/cheat.cpp
@@ -12,8 +12,10 @@
 #include "stdafx.h"
 #include "cheat_type.h"
 
+/** All the cheats. */
 Cheats _cheats;
 
+/** Reinitialise all the cheats. */
 void InitializeCheats()
 {
 	memset(&_cheats, 0, sizeof(Cheats));
diff --git a/src/clear_map.h b/src/clear_map.h
index ed5409a94..8a346fd4e 100644
--- a/src/clear_map.h
+++ b/src/clear_map.h
@@ -310,6 +310,7 @@ static inline void MakeField(TileIndex t, uint field_type, IndustryID industry)
 /**
  * Make a snow tile.
  * @param t the tile to make snowy
+ * @param density The density of snowiness.
  * @pre GetClearGround(t) != CLEAR_SNOW
  */
 static inline void MakeSnow(TileIndex t, uint density = 0)
diff --git a/src/company_cmd.cpp b/src/company_cmd.cpp
index 4944b66b1..46c310e82 100644
--- a/src/company_cmd.cpp
+++ b/src/company_cmd.cpp
@@ -393,7 +393,9 @@ bad_town_name:;
 	}
 }
 
+/** Sorting weights for the company colours. */
 static const byte _colour_sort[COLOUR_END] = {2, 2, 3, 2, 3, 2, 3, 2, 3, 2, 2, 2, 3, 1, 1, 1};
+/** Similar colours, so we can try to prevent same coloured companies. */
 static const Colours _similar_colour[COLOUR_END][2] = {
 	{ COLOUR_BLUE,       COLOUR_LIGHT_BLUE }, // COLOUR_DARK_BLUE
 	{ COLOUR_GREEN,      COLOUR_DARK_GREEN }, // COLOUR_PALE_GREEN
@@ -685,6 +687,7 @@ static void HandleBankruptcyTakeover(Company *c)
 	}
 }
 
+/** Called every tick for updating some company info. */
 void OnTick_Companies()
 {
 	if (_game_mode == GM_EDITOR) return;
diff --git a/src/company_gui.cpp b/src/company_gui.cpp
index 968a216d0..84040f080 100644
--- a/src/company_gui.cpp
+++ b/src/company_gui.cpp
@@ -2068,6 +2068,10 @@ static const WindowDesc _company_desc(
 	_nested_company_widgets, lengthof(_nested_company_widgets)
 );
 
+/**
+ * Show the window with the overview of the company.
+ * @param company The company to show the window for.
+ */
 void ShowCompany(CompanyID company)
 {
 	if (!Company::IsValidID(company)) return;
@@ -2175,7 +2179,10 @@ static const WindowDesc _buy_company_desc(
 	_nested_buy_company_widgets, lengthof(_nested_buy_company_widgets)
 );
 
-
+/**
+ * Show the query to buy another company.
+ * @param company The company to buy.
+ */
 void ShowBuyCompanyDialog(CompanyID company)
 {
 	AllocateWindowDescFront<BuyCompanyWindow>(&_buy_company_desc, company);
diff --git a/src/company_manager_face.h b/src/company_manager_face.h
index 80614a16f..43aabeecc 100644
--- a/src/company_manager_face.h
+++ b/src/company_manager_face.h
@@ -84,6 +84,7 @@ static const CompanyManagerFaceBitsInfo _cmf_info[] = {
 	/* CMFV_TIE_EARRING     */ { 28, 3, {  6,  3,  6,  3 }, { 0x372, 0x37F, 0x372, 0x3D1 } }, ///< Depends on CMFV_HAS_TIE_EARRING
 	/* CMFV_GLASSES         */ { 31, 1, {  2,  2,  2,  2 }, { 0x347, 0x347, 0x3AE, 0x3AE } }  ///< Depends on CMFV_HAS_GLASSES
 };
+/** Make sure the table's size is right. */
 assert_compile(lengthof(_cmf_info) == CMFV_END);
 
 /**
diff --git a/src/economy.cpp b/src/economy.cpp
index 584eea7c7..6f2604c27 100644
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -281,7 +281,11 @@ int UpdateCompanyRatingAndValue(Company *c, bool update)
 	return score;
 }
 
-/*  use INVALID_OWNER as new_owner to delete the company. */
+/**
+ * Change the ownership of all the items of a company.
+ * @param old_owner The company that gets removed.
+ * @param new_owner The company to merge to, or INVALID_OWNER to remove the company.
+ */
 void ChangeOwnershipOfCompanyItems(Owner old_owner, Owner new_owner)
 {
 	/* We need to set _current_company to old_owner before we try to move
diff --git a/src/tunnelbridge_cmd.cpp b/src/tunnelbridge_cmd.cpp
index 54a7c9370..51323f0c1 100644
--- a/src/tunnelbridge_cmd.cpp
+++ b/src/tunnelbridge_cmd.cpp
@@ -89,6 +89,12 @@ int CalcBridgeLenCostFactor(int length)
 	}
 }
 
+/**
+ * Get the foundation for a bridge.
+ * @param tileh The slope to build the bridge on.
+ * @param axis The axis of the bridge entrace.
+ * @return The foundatiton required.
+ */
 Foundation GetBridgeFoundation(Slope tileh, Axis axis)
 {
 	if (tileh == SLOPE_FLAT ||
@@ -1208,7 +1214,10 @@ static BridgePieces CalcBridgePiece(uint north, uint south)
 	}
 }
 
-
+/**
+ * Draw the middle bits of a bridge.
+ * @param ti Tile information of the tile to draw it on.
+ */
 void DrawBridgeMiddle(const TileInfo *ti)
 {
 	/* Sectional view of bridge bounding boxes: