(svn r21844) -Codechange: move documentation towards the code to make it more likely to be updates [a-c].

16 files changed, 250 insertions, 316 deletions

diff --git a/src/aircraft.h b/src/aircraft.h
index 6afe4ef61..ae48eb00e 100644
--- a/src/aircraft.h
+++ b/src/aircraft.h
@@ -26,31 +26,9 @@ enum AircraftSubType {
 };
 
 
-/**
- * Handle Aircraft specific tasks when an Aircraft enters a hangar
- * @param *v Vehicle that enters the hangar
- */
 void HandleAircraftEnterHangar(Aircraft *v);
-
-/**
- * Get the size of the sprite of an aircraft sprite heading west (used for lists)
- * @param engine The engine to get the sprite from
- * @param width The width of the sprite
- * @param height The height of the sprite
- */
 void GetAircraftSpriteSize(EngineID engine, uint &width, uint &height);
-
-/**
- * Updates the status of the Aircraft heading or in the station
- * @param st Station been updated
- */
 void UpdateAirplanesOnNewStation(const Station *st);
-
-/**
- * Update cached values of an aircraft.
- * Currently caches callback 36 max speed.
- * @param v Vehicle
- */
 void UpdateAircraftCache(Aircraft *v);
 
 void AircraftLeaveHangar(Aircraft *v);
diff --git a/src/aircraft_cmd.cpp b/src/aircraft_cmd.cpp
index 419d96ff4..58a46e4ad 100644
--- a/src/aircraft_cmd.cpp
+++ b/src/aircraft_cmd.cpp
@@ -533,6 +533,11 @@ static void PlayAircraftSound(const Vehicle *v)
 }
 
 
+/**
+ * Update cached values of an aircraft.
+ * Currently caches callback 36 max speed.
+ * @param v Vehicle
+ */
 void UpdateAircraftCache(Aircraft *v)
 {
 	uint max_speed = GetVehicleProperty(v, PROP_AIRCRAFT_SPEED, 0);
diff --git a/src/autoreplace.cpp b/src/autoreplace.cpp
index d72a937d0..18a5c4e3b 100644
--- a/src/autoreplace.cpp
+++ b/src/autoreplace.cpp
@@ -33,6 +33,11 @@ static EngineRenew *GetEngineReplacement(EngineRenewList erl, EngineID engine, G
 	return NULL;
 }
 
+/**
+ * Remove all engine replacement settings for the company.
+ * @param  erl The renewlist for a given company.
+ * @return The new renewlist for the company.
+ */
 void RemoveAllEngineReplacement(EngineRenewList *erl)
 {
 	EngineRenew *er = (EngineRenew *)(*erl);
@@ -46,6 +51,14 @@ void RemoveAllEngineReplacement(EngineRenewList *erl)
 	*erl = NULL; // Empty list
 }
 
+/**
+ * Retrieve the engine replacement in a given renewlist for an original engine type.
+ * @param erl The renewlist to search in.
+ * @param engine Engine type to be replaced.
+ * @param group The group related to this replacement.
+ * @return The engine type to replace with, or INVALID_ENGINE if no
+ * replacement is in the list.
+ */
 EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group)
 {
 	const EngineRenew *er = GetEngineReplacement(erl, engine, group);
@@ -56,6 +69,15 @@ EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group)
 	return er == NULL ? INVALID_ENGINE : er->to;
 }
 
+/**
+ * Add an engine replacement to the given renewlist.
+ * @param erl The renewlist to add to.
+ * @param old_engine The original engine type.
+ * @param new_engine The replacement engine type.
+ * @param group The group related to this replacement.
+ * @param flags The calling command flags.
+ * @return 0 on success, CMD_ERROR on failure.
+ */
 CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, EngineID new_engine, GroupID group, DoCommandFlag flags)
 {
 	/* Check if the old vehicle is already in the list */
@@ -79,6 +101,14 @@ CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, Engi
 	return CommandCost();
 }
 
+/**
+ * Remove an engine replacement from a given renewlist.
+ * @param erl The renewlist from which to remove the replacement
+ * @param engine The original engine type.
+ * @param group The group related to this replacement.
+ * @param flags The calling command flags.
+ * @return 0 on success, CMD_ERROR on failure.
+ */
 CommandCost RemoveEngineReplacement(EngineRenewList *erl, EngineID engine, GroupID group, DoCommandFlag flags)
 {
 	EngineRenew *er = (EngineRenew *)(*erl);
diff --git a/src/autoreplace_func.h b/src/autoreplace_func.h
index fd5c0568b..fdb889840 100644
--- a/src/autoreplace_func.h
+++ b/src/autoreplace_func.h
@@ -17,42 +17,9 @@
 #include "engine_type.h"
 #include "group_type.h"
 
-/**
- * Remove all engine replacement settings for the company.
- * @param  erl The renewlist for a given company.
- * @return The new renewlist for the company.
- */
 void RemoveAllEngineReplacement(EngineRenewList *erl);
-
-/**
- * Retrieve the engine replacement in a given renewlist for an original engine type.
- * @param erl The renewlist to search in.
- * @param engine Engine type to be replaced.
- * @param group The group related to this replacement.
- * @return The engine type to replace with, or INVALID_ENGINE if no
- * replacement is in the list.
- */
 EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group);
-
-/**
- * Add an engine replacement to the given renewlist.
- * @param erl The renewlist to add to.
- * @param old_engine The original engine type.
- * @param new_engine The replacement engine type.
- * @param group The group related to this replacement.
- * @param flags The calling command flags.
- * @return 0 on success, CMD_ERROR on failure.
- */
 CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, EngineID new_engine, GroupID group, DoCommandFlag flags);
-
-/**
- * Remove an engine replacement from a given renewlist.
- * @param erl The renewlist from which to remove the replacement
- * @param engine The original engine type.
- * @param group The group related to this replacement.
- * @param flags The calling command flags.
- * @return 0 on success, CMD_ERROR on failure.
- */
 CommandCost RemoveEngineReplacement(EngineRenewList *erl, EngineID engine, GroupID group, DoCommandFlag flags);
 
 /**
diff --git a/src/autoreplace_gui.h b/src/autoreplace_gui.h
index b9692616b..046ac8992 100644
--- a/src/autoreplace_gui.h
+++ b/src/autoreplace_gui.h
@@ -16,10 +16,6 @@
 #include "group_type.h"
 #include "vehicle_type.h"
 
-/**
- * When an engine is made buildable or is removed from being buildable, add/remove it from the build/autoreplace lists
- * @param type The type of engine
- */
 void AddRemoveEngineFromAutoreplaceAndBuildWindows(VehicleType type);
 void InvalidateAutoreplaceWindow(EngineID e, GroupID id_g);
 void ShowReplaceGroupVehicleWindow(GroupID group, VehicleType veh);
diff --git a/src/base_media_base.h b/src/base_media_base.h
index 273739cb9..a8fae72f2 100644
--- a/src/base_media_base.h
+++ b/src/base_media_base.h
@@ -104,14 +104,6 @@ struct BaseSet {
 		return Tnum_files - this->valid_files;
 	}
 
-	/**
-	 * Read the set information from a loaded ini.
-	 * @param ini      the ini to read from
-	 * @param path     the path to this ini file (for filenames)
-	 * @param full_filename the full filename of the loaded file (for error reporting purposes)
-	 * @param allow_empty_filename empty filenames are valid
-	 * @return true if loading was successful.
-	 */
 	bool FillSetDetails(IniFile *ini, const char *path, const char *full_filename, bool allow_empty_filename = true);
 
 	/**
@@ -177,42 +169,11 @@ public:
 		return fs.Scan(GetExtension(), Tbase_set::SUBDIR, Tbase_set::SUBDIR != GM_DIR);
 	}
 
-	/**
-	 * Set the set to be used.
-	 * @param name of the set to use
-	 * @return true if it could be loaded
-	 */
 	static bool SetSet(const char *name);
-
-	/**
-	 * Returns a list with the sets.
-	 * @param p    where to print to
-	 * @param last the last character to print to
-	 * @return the last printed character
-	 */
 	static char *GetSetsList(char *p, const char *last);
-
-	/**
-	 * Count the number of available graphics sets.
-	 * @return the number of sets
-	 */
 	static int GetNumSets();
-
-	/**
-	 * Get the index of the currently active graphics set
-	 * @return the current set's index
-	 */
 	static int GetIndexOfUsedSet();
-
-	/**
-	 * Get the name of the graphics set at the specified index
-	 * @return the name of the set
-	 */
 	static const Tbase_set *GetSet(int index);
-	/**
-	 * Return the used set.
-	 * @return the used set.
-	 */
 	static const Tbase_set *GetUsedSet();
 
 	/**
diff --git a/src/base_media_func.h b/src/base_media_func.h
index c7b3a471f..69eaccf5f 100644
--- a/src/base_media_func.h
+++ b/src/base_media_func.h
@@ -31,6 +31,14 @@ template <class Tbase_set> /* static */ Tbase_set *BaseMedia<Tbase_set>::duplica
 		return false; \
 	}
 
+/**
+ * Read the set information from a loaded ini.
+ * @param ini      the ini to read from
+ * @param path     the path to this ini file (for filenames)
+ * @param full_filename the full filename of the loaded file (for error reporting purposes)
+ * @param allow_empty_filename empty filenames are valid
+ * @return true if loading was successful.
+ */
 template <class T, size_t Tnum_files, Subdirectory Tsubdir>
 bool BaseSet<T, Tnum_files, Tsubdir>::FillSetDetails(IniFile *ini, const char *path, const char *full_filename, bool allow_empty_filename)
 {
@@ -208,6 +216,11 @@ bool BaseMedia<Tbase_set>::AddFile(const char *filename, size_t basepath_length)
 	return ret;
 }
 
+/**
+ * Set the set to be used.
+ * @param name of the set to use
+ * @return true if it could be loaded
+ */
 template <class Tbase_set>
 /* static */ bool BaseMedia<Tbase_set>::SetSet(const char *name)
 {
@@ -229,6 +242,12 @@ template <class Tbase_set>
 	return false;
 }
 
+/**
+ * Returns a list with the sets.
+ * @param p    where to print to
+ * @param last the last character to print to
+ * @return the last printed character
+ */
 template <class Tbase_set>
 /* static */ char *BaseMedia<Tbase_set>::GetSetsList(char *p, const char *last)
 {
@@ -293,6 +312,10 @@ template <class Tbase_set>
 
 #endif /* ENABLE_NETWORK */
 
+/**
+ * Count the number of available graphics sets.
+ * @return the number of sets
+ */
 template <class Tbase_set>
 /* static */ int BaseMedia<Tbase_set>::GetNumSets()
 {
@@ -304,6 +327,10 @@ template <class Tbase_set>
 	return n;
 }
 
+/**
+ * Get the index of the currently active graphics set
+ * @return the current set's index
+ */
 template <class Tbase_set>
 /* static */ int BaseMedia<Tbase_set>::GetIndexOfUsedSet()
 {
@@ -316,6 +343,10 @@ template <class Tbase_set>
 	return -1;
 }
 
+/**
+ * Get the name of the graphics set at the specified index
+ * @return the name of the set
+ */
 template <class Tbase_set>
 /* static */ const Tbase_set *BaseMedia<Tbase_set>::GetSet(int index)
 {
@@ -327,6 +358,10 @@ template <class Tbase_set>
 	error("Base" SET_TYPE "::GetSet(): index %d out of range", index);
 }
 
+/**
+ * Return the used set.
+ * @return the used set.
+ */
 template <class Tbase_set>
 /* static */ const Tbase_set *BaseMedia<Tbase_set>::GetUsedSet()
 {
diff --git a/src/bridge_map.cpp b/src/bridge_map.cpp
index 9fb4cf413..c89af44d5 100644
--- a/src/bridge_map.cpp
+++ b/src/bridge_map.cpp
@@ -32,24 +32,41 @@ static TileIndex GetBridgeEnd(TileIndex tile, DiagDirection dir)
 }
 
 
+/**
+ * Finds the northern end of a bridge starting at a middle tile
+ * @param t the bridge tile to find the bridge ramp for
+ */
 TileIndex GetNorthernBridgeEnd(TileIndex t)
 {
 	return GetBridgeEnd(t, ReverseDiagDir(AxisToDiagDir(GetBridgeAxis(t))));
 }
 
 
+/**
+ * Finds the southern end of a bridge starting at a middle tile
+ * @param t the bridge tile to find the bridge ramp for
+ */
 TileIndex GetSouthernBridgeEnd(TileIndex t)
 {
 	return GetBridgeEnd(t, AxisToDiagDir(GetBridgeAxis(t)));
 }
 
 
+/**
+ * Starting at one bridge end finds the other bridge end
+ * @param t the bridge ramp tile to find the other bridge ramp for
+ */
 TileIndex GetOtherBridgeEnd(TileIndex tile)
 {
 	assert(IsBridgeTile(tile));
 	return GetBridgeEnd(tile, GetTunnelBridgeDirection(tile));
 }
 
+/**
+ * Get the height ('z') of a bridge in pixels.
+ * @param tile the bridge ramp tile to get the bridge height from
+ * @return the height of the bridge in pixels
+ */
 uint GetBridgeHeight(TileIndex t)
 {
 	uint h;
diff --git a/src/bridge_map.h b/src/bridge_map.h
index 796bae28a..729858281 100644
--- a/src/bridge_map.h
+++ b/src/bridge_map.h
@@ -85,30 +85,10 @@ static inline Axis GetBridgeAxis(TileIndex t)
 	return (Axis)(GB(_m[t].m6, 6, 2) - 1);
 }
 
-/**
- * Finds the northern end of a bridge starting at a middle tile
- * @param t the bridge tile to find the bridge ramp for
- */
 TileIndex GetNorthernBridgeEnd(TileIndex t);
-
-/**
- * Finds the southern end of a bridge starting at a middle tile
- * @param t the bridge tile to find the bridge ramp for
- */
 TileIndex GetSouthernBridgeEnd(TileIndex t);
-
-
-/**
- * Starting at one bridge end finds the other bridge end
- * @param t the bridge ramp tile to find the other bridge ramp for
- */
 TileIndex GetOtherBridgeEnd(TileIndex t);
 
-/**
- * Get the height ('z') of a bridge in pixels.
- * @param tile the bridge ramp tile to get the bridge height from
- * @return the height of the bridge in pixels
- */
 uint GetBridgeHeight(TileIndex tile);
 
 /**
diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp
index 418eb8e83..e73341ff3 100644
--- a/src/cargopacket.cpp
+++ b/src/cargopacket.cpp
@@ -25,14 +25,26 @@ void InitializeCargoPackets()
 	_cargopacket_pool.CleanPool();
 }
 
+/**
+ * Create a new packet for savegame loading.
+ */
 CargoPacket::CargoPacket()
 {
 	this->source_type = ST_INDUSTRY;
 	this->source_id   = INVALID_SOURCE;
 }
 
-/* NOTE: We have to zero memory ourselves here because we are using a 'new'
- * that, in contrary to all other pools, does not memset to 0. */
+/**
+ * Creates a new cargo packet
+ * @param source      the source station of the packet
+ * @param source_xy   the source location of the packet
+ * @param count       the number of cargo entities to put in this packet
+ * @param source_type the 'type' of source the packet comes from (for subsidies)
+ * @param source_id   the actual source of the packet (for subsidies)
+ * @pre count != 0
+ * @note We have to zero memory ourselves here because we are using a 'new'
+ * that, in contrary to all other pools, does not memset to 0.
+ */
 CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id) :
 	feeder_share(0),
 	count(count),
@@ -46,6 +58,18 @@ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, So
 	this->source_type  = source_type;
 }
 
+/**
+ * Creates a new cargo packet. Initializes the fields that cannot be changed later.
+ * Used when loading or splitting packets.
+ * @param count           the number of cargo entities to put in this packet
+ * @param days_in_transit number of days the cargo has been in transit
+ * @param source          the station the cargo was initially loaded
+ * @param source_xy       the station location the cargo was initially loaded
+ * @param loaded_at_xy    the location the cargo was loaded last
+ * @param feeder_share    feeder share the packet has already accumulated
+ * @param source_type     the 'type' of source the packet comes from (for subsidies)
+ * @param source_id       the actual source of the packet (for subsidies)
+ */
 CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share, SourceType source_type, SourceID source_id) :
 		feeder_share(feeder_share),
 		count(count),
@@ -90,6 +114,7 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T
  *
  */
 
+/** Destroy it ("frees" all cargo packets) */
 template <class Tinst>
 CargoList<Tinst>::~CargoList()
 {
@@ -98,6 +123,11 @@ CargoList<Tinst>::~CargoList()
 	}
 }
 
+/**
+ * Update the cached values to reflect the removal of this packet.
+ * Decreases count and days_in_transit
+ * @param cp Packet to be removed from cache
+ */
 template <class Tinst>
 void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp)
 {
@@ -105,6 +135,11 @@ void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp)
 	this->cargo_days_in_transit -= cp->days_in_transit * cp->count;
 }
 
+/**
+ * Update the cache to reflect adding of this packet.
+ * Increases count and days_in_transit
+ * @param cp a new packet to be inserted
+ */
 template <class Tinst>
 void CargoList<Tinst>::AddToCache(const CargoPacket *cp)
 {
@@ -112,6 +147,13 @@ void CargoList<Tinst>::AddToCache(const CargoPacket *cp)
 	this->cargo_days_in_transit += cp->days_in_transit * cp->count;
 }
 
+/**
+ * Appends the given cargo packet
+ * @warning After appending this packet may not exist anymore!
+ * @note Do not use the cargo packet anymore after it has been appended to this CargoList!
+ * @param cp the cargo packet to add
+ * @pre cp != NULL
+ */
 template <class Tinst>
 void CargoList<Tinst>::Append(CargoPacket *cp)
 {
@@ -134,6 +176,11 @@ void CargoList<Tinst>::Append(CargoPacket *cp)
 }
 
 
+/**
+ * Truncates the cargo in this list to the given amount. It leaves the
+ * first count cargo entities and removes the rest.
+ * @param max_remaining the maximum amount of entities to be in the list after the command
+ */
 template <class Tinst>
 void CargoList<Tinst>::Truncate(uint max_remaining)
 {
@@ -161,6 +208,27 @@ void CargoList<Tinst>::Truncate(uint max_remaining)
 	}
 }
 
+/**
+ * Moves the given amount of cargo to another list.
+ * Depending on the value of mta the side effects of this function differ:
+ *  - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station
+ *  - MTA_CARGO_LOAD:     sets the loaded_at_xy value of the moved packets
+ *  - MTA_TRANSFER:       just move without side effects
+ *  - MTA_UNLOAD:         just move without side effects
+ * @param dest  the destination to move the cargo to
+ * @param count the 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
+ *              - MTA_CARGO_LOAD     - station's tile index of load
+ *              - MTA_TRANSFER       - unused
+ *              - MTA_UNLOAD         - unused
+ * @param payment The payment helper
+ *
+ * @pre mta == MTA_FINAL_DELIVERY || dest != NULL
+ * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL
+ * @return true if there are still packets that might be moved from this cargo list
+ */
 template <class Tinst>
 template <class Tother_inst>
 bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta, CargoPayment *payment, uint data)
@@ -240,6 +308,7 @@ bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta
 	return it != packets.end();
 }
 
+/** Invalidates the cached data and rebuild it */
 template <class Tinst>
 void CargoList<Tinst>::InvalidateCache()
 {
@@ -252,18 +321,31 @@ void CargoList<Tinst>::InvalidateCache()
 }
 
 
+/**
+ * Update the cached values to reflect the removal of this packet.
+ * Decreases count, feeder share and days_in_transit
+ * @param cp Packet to be removed from cache
+ */
 void VehicleCargoList::RemoveFromCache(const CargoPacket *cp)
 {
 	this->feeder_share -= cp->feeder_share;
 	this->Parent::RemoveFromCache(cp);
 }
 
+/**
+ * Update the cache to reflect adding of this packet.
+ * Increases count, feeder share and days_in_transit
+ * @param cp a new packet to be inserted
+ */
 void VehicleCargoList::AddToCache(const CargoPacket *cp)
 {
 	this->feeder_share += cp->feeder_share;
 	this->Parent::AddToCache(cp);
 }
 
+/**
+ * Ages the all cargo in this list
+ */
 void VehicleCargoList::AgeCargo()
 {
 	for (ConstIterator it(this->packets.begin()); it != this->packets.end(); it++) {
@@ -276,6 +358,7 @@ void VehicleCargoList::AgeCargo()
 	}
 }
 
+/** Invalidates the cached data and rebuild it */
 void VehicleCargoList::InvalidateCache()
 {
 	this->feeder_share = 0;
diff --git a/src/cargopacket.h b/src/cargopacket.h
index 77f656bcf..68ba629cf 100644
--- a/src/cargopacket.h
+++ b/src/cargopacket.h
@@ -55,34 +55,8 @@ public:
 	/** Maximum number of items in a single cargo packet. */
 	static const uint16 MAX_COUNT = UINT16_MAX;
 
-	/**
-	 * Create a new packet for savegame loading.
-	 */
 	CargoPacket();
-
-	/**
-	 * Creates a new cargo packet
-	 * @param source      the source station of the packet
-	 * @param source_xy   the source location of the packet
-	 * @param count       the number of cargo entities to put in this packet
-	 * @param source_type the 'type' of source the packet comes from (for subsidies)
-	 * @param source_id   the actual source of the packet (for subsidies)
-	 * @pre count != 0
-	 */
 	CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id);
-
-	/**
-	 * Creates a new cargo packet. Initializes the fields that cannot be changed later.
-	 * Used when loading or splitting packets.
-	 * @param count           the number of cargo entities to put in this packet
-	 * @param days_in_transit number of days the cargo has been in transit
-	 * @param source          the station the cargo was initially loaded
-	 * @param source_xy       the station location the cargo was initially loaded
-	 * @param loaded_at_xy    the location the cargo was loaded last
-	 * @param feeder_share    feeder share the packet has already accumulated
-	 * @param source_type     the 'type' of source the packet comes from (for subsidies)
-	 * @param source_id       the actual source of the packet (for subsidies)
-	 */
 	CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share = 0, SourceType source_type = ST_INDUSTRY, SourceID source_id = INVALID_SOURCE);
 
 	/** Destroy the packet */
@@ -211,24 +185,12 @@ protected:
 
 	List packets;               ///< The cargo packets in this list
 
-	/**
-	 * Update the cache to reflect adding of this packet.
-	 * Increases count and days_in_transit
-	 * @param cp a new packet to be inserted
-	 */
 	void AddToCache(const CargoPacket *cp);
-
-	/**
-	 * Update the cached values to reflect the removal of this packet.
-	 * Decreases count and days_in_transit
-	 * @param cp Packet to be removed from cache
-	 */
 	void RemoveFromCache(const CargoPacket *cp);
 
 public:
 	/** Create the cargo list */
 	CargoList() {}
-	/** And destroy it ("frees" all cargo packets) */
 	~CargoList();
 
 	/**
@@ -277,47 +239,12 @@ public:
 	}
 
 
-	/**
-	 * Appends the given cargo packet
-	 * @warning After appending this packet may not exist anymore!
-	 * @note Do not use the cargo packet anymore after it has been appended to this CargoList!
-	 * @param cp the cargo packet to add
-	 * @pre cp != NULL
-	 */
 	void Append(CargoPacket *cp);
-
-	/**
-	 * Truncates the cargo in this list to the given amount. It leaves the
-	 * first count cargo entities and removes the rest.
-	 * @param max_remaining the maximum amount of entities to be in the list after the command
-	 */
 	void Truncate(uint max_remaining);
 
-	/**
-	 * Moves the given amount of cargo to another list.
-	 * Depending on the value of mta the side effects of this function differ:
-	 *  - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station
-	 *  - MTA_CARGO_LOAD:     sets the loaded_at_xy value of the moved packets
-	 *  - MTA_TRANSFER:       just move without side effects
-	 *  - MTA_UNLOAD:         just move without side effects
-	 * @param dest  the destination to move the cargo to
-	 * @param count the 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
-	 *              - MTA_CARGO_LOAD     - station's tile index of load
-	 *              - MTA_TRANSFER       - unused
-	 *              - MTA_UNLOAD         - unused
-	 * @param payment The payment helper
-	 *
-	 * @pre mta == MTA_FINAL_DELIVERY || dest != NULL
-	 * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL
-	 * @return true if there are still packets that might be moved from this cargo list
-	 */
 	template <class Tother_inst>
 	bool MoveTo(Tother_inst *dest, uint count, MoveToAction mta, CargoPayment *payment, uint data = 0);
 
-	/** Invalidates the cached data and rebuild it */
 	void InvalidateCache();
 };
 
@@ -331,18 +258,7 @@ protected:
 
 	Money feeder_share; ///< Cache for the feeder share
 
-	/**
-	 * Update the cache to reflect adding of this packet.
-	 * Increases count, feeder share and days_in_transit
-	 * @param cp a new packet to be inserted
-	 */
 	void AddToCache(const CargoPacket *cp);
-
-	/**
-	 * Update the cached values to reflect the removal of this packet.
-	 * Decreases count, feeder share and days_in_transit
-	 * @param cp Packet to be removed from cache
-	 */
 	void RemoveFromCache(const CargoPacket *cp);
 
 public:
@@ -360,12 +276,8 @@ public:
 		return this->feeder_share;
 	}
 
-	/**
-	 * Ages the all cargo in this list
-	 */
 	void AgeCargo();
 
-	/** Invalidates the cached data and rebuild it */
 	void InvalidateCache();
 
 	/**
diff --git a/src/cheat.cpp b/src/cheat.cpp
index a7e967a98..a0df14982 100644
--- a/src/cheat.cpp
+++ b/src/cheat.cpp
@@ -19,6 +19,10 @@ void InitializeCheats()
 	memset(&_cheats, 0, sizeof(Cheats));
 }
 
+/**
+ * Return true if any cheat has been used, false otherwise
+ * @return has a cheat been used?
+ */
 bool CheatHasBeenUsed()
 {
 	/* Cannot use lengthof because _cheats is of type Cheats, not Cheat */
diff --git a/src/cheat_func.h b/src/cheat_func.h
index c75f9d3d7..e774abc68 100644
--- a/src/cheat_func.h
+++ b/src/cheat_func.h
@@ -18,10 +18,6 @@ extern Cheats _cheats;
 
 void ShowCheatWindow();
 
-/**
- * Return true if any cheat has been used, false otherwise
- * @return has a cheat been used?
- */
 bool CheatHasBeenUsed();
 
 #endif /* CHEAT_FUNC_H */
diff --git a/src/command_func.h b/src/command_func.h
index 212e71ddf..c741c7924 100644
--- a/src/command_func.h
+++ b/src/command_func.h
@@ -34,47 +34,24 @@ static const CommandCost CMD_ERROR = CommandCost(INVALID_STRING_ID);
  */
 #define return_cmd_error(errcode) return CommandCost(errcode);
 
-/**
- * Execute a command
- */
 CommandCost DoCommand(TileIndex tile, uint32 p1, uint32 p2, DoCommandFlag flags, uint32 cmd, const char *text = NULL);
 CommandCost DoCommand(const CommandContainer *container, DoCommandFlag flags);
 
-/**
- * Execute a network safe DoCommand function
- */
 bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback = NULL, const char *text = NULL, bool my_cmd = true);
 bool DoCommandP(const CommandContainer *container, bool my_cmd = true);
 
-/** Internal helper function for DoCommandP. Do not use. */
 CommandCost DoCommandPInternal(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback, const char *text, bool my_cmd, bool estimate_only);
 
 #ifdef ENABLE_NETWORK
-/**
- * Send a command over the network
- */
 void NetworkSendCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback, const char *text, CompanyID company);
 #endif /* ENABLE_NETWORK */
 
 extern Money _additional_cash_required;
 
-/**
- * Checks if a integer value belongs to a command.
- */
 bool IsValidCommand(uint32 cmd);
-/**
- * Returns the flags from a given command.
- */
 byte GetCommandFlags(uint32 cmd);
-/**
- * Returns the name of a given command.
- */
 const char *GetCommandName(uint32 cmd);
-/**
- * Returns the current money available which can be used for a command.
- */
 Money GetAvailableMoneyForCommand();
-
 bool IsCommandAllowedWhilePaused(uint32 cmd);
 
 /**
diff --git a/src/crashlog.cpp b/src/crashlog.cpp
index e47a65ed7..bda4d674f 100644
--- a/src/crashlog.cpp
+++ b/src/crashlog.cpp
@@ -73,6 +73,12 @@ char *CrashLog::LogCompiler(char *buffer, const char *last) const
 	return buffer;
 }
 
+/**
+ * Writes OpenTTD's version to the buffer.
+ * @param buffer The begin where to write at.
+ * @param last   The last position in the buffer to write to.
+ * @return the position of the \c '\0' character after the buffer.
+ */
 char *CrashLog::LogOpenTTDVersion(char *buffer, const char *last) const
 {
 	return buffer + seprintf(buffer, last,
@@ -105,6 +111,13 @@ char *CrashLog::LogOpenTTDVersion(char *buffer, const char *last) const
 	);
 }
 
+/**
+ * Writes the (important) configuration settings to the buffer.
+ * E.g. graphics set, sound set, blitter and AIs.
+ * @param buffer The begin where to write at.
+ * @param last   The last position in the buffer to write to.
+ * @return the position of the \c '\0' character after the buffer.
+ */
 char *CrashLog::LogConfiguration(char *buffer, const char *last) const
 {
 	buffer += seprintf(buffer, last,
@@ -181,6 +194,12 @@ char *CrashLog::LogConfiguration(char *buffer, const char *last) const
 # include <zlib.h>
 #endif
 
+/**
+ * Writes information (versions) of the used libraries.
+ * @param buffer The begin where to write at.
+ * @param last   The last position in the buffer to write to.
+ * @return the position of the \c '\0' character after the buffer.
+ */
 char *CrashLog::LogLibraries(char *buffer, const char *last) const
 {
 	buffer += seprintf(buffer, last, "Libraries:\n");
@@ -243,11 +262,21 @@ char *CrashLog::LogLibraries(char *buffer, const char *last) const
 	return buffer;
 }
 
+/**
+ * Helper function for printing the gamelog.
+ * @param s the string to print.
+ */
 /* static */ void CrashLog::GamelogFillCrashLog(const char *s)
 {
 	CrashLog::gamelog_buffer += seprintf(CrashLog::gamelog_buffer, CrashLog::gamelog_last, "%s\n", s);
 }
 
+/**
+ * Writes the gamelog data to the buffer.
+ * @param buffer The begin where to write at.
+ * @param last   The last position in the buffer to write to.
+ * @return the position of the \c '\0' character after the buffer.
+ */
 char *CrashLog::LogGamelog(char *buffer, const char *last) const
 {
 	CrashLog::gamelog_buffer = buffer;
@@ -256,6 +285,12 @@ char *CrashLog::LogGamelog(char *buffer, const char *last) const
 	return CrashLog::gamelog_buffer + seprintf(CrashLog::gamelog_buffer, last, "\n");
 }
 
+/**
+ * Fill the crash log buffer with all data of a crash log.
+ * @param buffer The begin where to write at.
+ * @param last   The last position in the buffer to write to.
+ * @return the position of the \c '\0' character after the buffer.
+ */
 char *CrashLog::FillCrashLog(char *buffer, const char *last) const
 {
 	time_t cur_time = time(NULL);
@@ -281,6 +316,15 @@ char *CrashLog::FillCrashLog(char *buffer, const char *last) const
 	return buffer;
 }
 
+/**
+ * Write the crash log to a file.
+ * @note On success the filename will be filled with the full path of the
+ *       crash log file. Make sure filename is at least \c MAX_PATH big.
+ * @param buffer The begin of the buffer to write to the disk.
+ * @param filename      Output for the filename of the written file.
+ * @param filename_last The last position in the filename buffer.
+ * @return true when the crash log was successfully written.
+ */
 bool CrashLog::WriteCrashLog(const char *buffer, char *filename, const char *filename_last) const
 {
 	seprintf(filename, filename_last, "%scrash.log", _personal_dir);
@@ -301,6 +345,14 @@ bool CrashLog::WriteCrashLog(const char *buffer, char *filename, const char *fil
 	return 0;
 }
 
+/**
+ * Write the (crash) savegame to a file.
+ * @note On success the filename will be filled with the full path of the
+ *       crash save file. Make sure filename is at least \c MAX_PATH big.
+ * @param filename      Output for the filename of the written file.
+ * @param filename_last The last position in the filename buffer.
+ * @return true when the crash save was successfully made.
+ */
 bool CrashLog::WriteSavegame(char *filename, const char *filename_last) const
 {
 	/* If the map array doesn't exist, saving will fail too. If the map got
@@ -319,6 +371,14 @@ bool CrashLog::WriteSavegame(char *filename, const char *filename_last) const
 	}
 }
 
+/**
+ * Write the (crash) screenshot to a file.
+ * @note On success the filename will be filled with the full path of the
+ *       screenshot. Make sure filename is at least \c MAX_PATH big.
+ * @param filename      Output for the filename of the written file.
+ * @param filename_last The last position in the filename buffer.
+ * @return true when the crash screenshot was successfully made.
+ */
 bool CrashLog::WriteScreenshot(char *filename, const char *filename_last) const
 {
 	/* Don't draw when we have invalid screen size */
@@ -329,6 +389,12 @@ bool CrashLog::WriteScreenshot(char *filename, const char *filename_last) const
 	return res;
 }
 
+/**
+ * Makes the crash log, writes it to a file and then subsequently tries
+ * to make a crash dump and crash savegame. It uses DEBUG to write
+ * information like paths to the console.
+ * @return true when everything is made successfully.
+ */
 bool CrashLog::MakeCrashLog() const
 {
 	/* Don't keep looping logging crashes. */
@@ -384,11 +450,19 @@ bool CrashLog::MakeCrashLog() const
 	return ret;
 }
 
+/**
+ * Sets a message for the error message handler.
+ * @param message The error message of the error.
+ */
 /* static */ void CrashLog::SetErrorMessage(const char *message)
 {
 	CrashLog::message = message;
 }
 
+/**
+ * Try to close the sound/video stuff so it doesn't keep lingering around
+ * incorrect video states or so, e.g. keeping dpmi disabled.
+ */
 /* static */ void CrashLog::AfterCrashLogCleanup()
 {
 	if (_music_driver != NULL) _music_driver->Stop();
diff --git a/src/crashlog.h b/src/crashlog.h
index e7f1f9342..4dd8c83d8 100644
--- a/src/crashlog.h
+++ b/src/crashlog.h
@@ -26,10 +26,6 @@ private:
 	/** Temporary 'local' location of the end of the buffer. */
 	static const char *gamelog_last;
 
-	/**
-	 * Helper function for printing the gamelog.
-	 * @param s the string to print.
-	 */
 	static void GamelogFillCrashLog(const char *s);
 protected:
 	/**
@@ -85,60 +81,16 @@ protected:
 	virtual char *LogModules(char *buffer, const char *last) const;
 
 
-	/**
-	 * Writes OpenTTD's version to the buffer.
-	 * @param buffer The begin where to write at.
-	 * @param last   The last position in the buffer to write to.
-	 * @return the position of the \c '\0' character after the buffer.
-	 */
 	char *LogOpenTTDVersion(char *buffer, const char *last) const;
-
-	/**
-	 * Writes the (important) configuration settings to the buffer.
-	 * E.g. graphics set, sound set, blitter and AIs.
-	 * @param buffer The begin where to write at.
-	 * @param last   The last position in the buffer to write to.
-	 * @return the position of the \c '\0' character after the buffer.
-	 */
 	char *LogConfiguration(char *buffer, const char *last) const;
-
-	/**
-	 * Writes information (versions) of the used libraries.
-	 * @param buffer The begin where to write at.
-	 * @param last   The last position in the buffer to write to.
-	 * @return the position of the \c '\0' character after the buffer.
-	 */
 	char *LogLibraries(char *buffer, const char *last) const;
-
-	/**
-	 * Writes the gamelog data to the buffer.
-	 * @param buffer The begin where to write at.
-	 * @param last   The last position in the buffer to write to.
-	 * @return the position of the \c '\0' character after the buffer.
-	 */
 	char *LogGamelog(char *buffer, const char *last) const;
 
 public:
 	/** Stub destructor to silence some compilers. */
 	virtual ~CrashLog() {}
 
-	/**
-	 * Fill the crash log buffer with all data of a crash log.
-	 * @param buffer The begin where to write at.
-	 * @param last   The last position in the buffer to write to.
-	 * @return the position of the \c '\0' character after the buffer.
-	 */
 	char *FillCrashLog(char *buffer, const char *last) const;
-
-	/**
-	 * Write the crash log to a file.
-	 * @note On success the filename will be filled with the full path of the
-	 *       crash log file. Make sure filename is at least \c MAX_PATH big.
-	 * @param buffer The begin of the buffer to write to the disk.
-	 * @param filename      Output for the filename of the written file.
-	 * @param filename_last The last position in the filename buffer.
-	 * @return true when the crash log was successfully written.
-	 */
 	bool WriteCrashLog(const char *buffer, char *filename, const char *filename_last) const;
 
 	/**
@@ -151,33 +103,9 @@ public:
 	 *         was successful (not all OSes support dumping files).
 	 */
 	virtual int WriteCrashDump(char *filename, const char *filename_last) const;
-
-	/**
-	 * Write the (crash) savegame to a file.
-	 * @note On success the filename will be filled with the full path of the
-	 *       crash save file. Make sure filename is at least \c MAX_PATH big.
-	 * @param filename      Output for the filename of the written file.
-	 * @param filename_last The last position in the filename buffer.
-	 * @return true when the crash save was successfully made.
-	 */
 	bool WriteSavegame(char *filename, const char *filename_last) const;
-
-	/**
-	 * Write the (crash) screenshot to a file.
-	 * @note On success the filename will be filled with the full path of the
-	 *       screenshot. Make sure filename is at least \c MAX_PATH big.
-	 * @param filename      Output for the filename of the written file.
-	 * @param filename_last The last position in the filename buffer.
-	 * @return true when the crash screenshot was successfully made.
-	 */
 	bool WriteScreenshot(char *filename, const char *filename_last) const;
 
-	/**
-	 * Makes the crash log, writes it to a file and then subsequently tries
-	 * to make a crash dump and crash savegame. It uses DEBUG to write
-	 * information like paths to the console.
-	 * @return true when everything is made successfully.
-	 */
 	bool MakeCrashLog() const;
 
 	/**
@@ -187,16 +115,7 @@ public:
 	 */
 	static void InitialiseCrashLog();
 
-	/**
-	 * Sets a message for the error message handler.
-	 * @param message The error message of the error.
-	 */
 	static void SetErrorMessage(const char *message);
-
-	/**
-	 * Try to close the sound/video stuff so it doesn't keep lingering around
-	 * incorrect video states or so, e.g. keeping dpmi disabled.
-	 */
 	static void AfterCrashLogCleanup();
 };