Mercurial > hg > openttd

changeset 17109:69b5b1b3eddd draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(svn r21846) -Codechange: move documentation towards the code to make it more likely to be updated [o-s].
author rubidium <rubidium@openttd.org>
date Tue, 18 Jan 2011 23:09:43 +0000
parents 5ae3089defb2
children 2bf4a68e98fd
files src/object.h src/object_base.h src/object_cmd.cpp src/order_backup.cpp src/order_backup.h src/order_base.h src/order_cmd.cpp src/order_func.h src/rail.cpp src/rail.h src/rail_cmd.cpp src/rail_map.h src/road.cpp src/road_func.h src/road_internal.h src/road_map.cpp src/road_map.h src/saveload/order_sl.cpp src/signs.cpp src/signs_base.h src/station.cpp src/station_base.h src/string.cpp src/string_func.h
diffstat 24 files changed, 360 insertions(+), 409 deletions(-) [+]
line wrap: on
line diff
--- a/src/object.h
+++ b/src/object.h
@@ -16,23 +16,8 @@
 #include "company_type.h"
 #include "object_type.h"
 
-/**
- * Update the CompanyHQ to the state associated with the given score
- * @param tile  The (northern) tile of the company HQ, or INVALID_TILE.
- * @param score The current (performance) score of the company.
- */
 void UpdateCompanyHQ(TileIndex tile, uint score);
 
-/**
- * Actually build the object.
- * @param type  The type of object to build.
- * @param tile  The tile to build the northern tile of the object on.
- * @param owner The owner of the object.
- * @param town  Town the tile is related with.
- * @param view  The view for the object.
- * @pre All preconditions for building the object at that location
- *      are met, e.g. slope and clearness of tiles are checked.
- */
 void BuildObject(ObjectType type, TileIndex tile, CompanyID owner = OWNER_NONE, struct Town *town = NULL, uint8 view = 0);
 
 void PlaceProc_Object(TileIndex tile);
--- a/src/object_base.h
+++ b/src/object_base.h
@@ -35,11 +35,6 @@
 	/** Make sure the right destructor is called as well! */
 	~Object() {}
 
-	/**
-	 * Get the object associated with a tile.
-	 * @param tile The tile to fetch the object for.
-	 * @return The object.
-	 */
 	static Object *GetByTile(TileIndex tile);
 
 	/**
--- a/src/object_cmd.cpp
+++ b/src/object_cmd.cpp
@@ -43,6 +43,11 @@
 INSTANTIATE_POOL_METHODS(Object)
 uint16 Object::counts[NUM_OBJECTS];
 
+/**
+ * Get the object associated with a tile.
+ * @param tile The tile to fetch the object for.
+ * @return The object.
+ */
 /* static */ Object *Object::GetByTile(TileIndex tile)
 {
 	return Object::Get(GetObjectIndex(tile));
@@ -55,6 +60,16 @@
 	Object::ResetTypeCounts();
 }
 
+/**
+ * Actually build the object.
+ * @param type  The type of object to build.
+ * @param tile  The tile to build the northern tile of the object on.
+ * @param owner The owner of the object.
+ * @param town  Town the tile is related with.
+ * @param view  The view for the object.
+ * @pre All preconditions for building the object at that location
+ *      are met, e.g. slope and clearness of tiles are checked.
+ */
 void BuildObject(ObjectType type, TileIndex tile, CompanyID owner, Town *town, uint8 view)
 {
 	const ObjectSpec *spec = ObjectSpec::Get(type);
@@ -113,6 +128,11 @@
 /** We encode the company HQ size in the animation stage. */
 #define IncreaseCompanyHQSize IncreaseAnimationStage
 
+/**
+ * Update the CompanyHQ to the state associated with the given score
+ * @param tile  The (northern) tile of the company HQ, or INVALID_TILE.
+ * @param score The current (performance) score of the company.
+ */
 void UpdateCompanyHQ(TileIndex tile, uint score)
 {
 	if (tile == INVALID_TILE) return;
--- a/src/order_backup.cpp
+++ b/src/order_backup.cpp
@@ -20,6 +20,7 @@
 OrderBackupPool _order_backup_pool("BackupOrder");
 INSTANTIATE_POOL_METHODS(OrderBackup)
 
+/** Free everything that is allocated. */
 OrderBackup::~OrderBackup()
 {
 	free(this->name);
@@ -34,6 +35,11 @@
 	}
 }
 
+/**
+ * Create an order backup for the given vehicle.
+ * @param v    The vehicle to make a backup of.
+ * @param user The user that is requesting the backup.
+ */
 OrderBackup::OrderBackup(const Vehicle *v, uint32 user)
 {
 	this->user             = user;
@@ -62,6 +68,10 @@
 	}
 }
 
+/**
+ * Restore the data of this order to the given vehicle.
+ * @param v The vehicle to restore to.
+ */
 void OrderBackup::DoRestore(Vehicle *v)
 {
 	/* If we have a custom name, process that */
@@ -84,6 +94,12 @@
 	DoCommand(0, this->group, v->index, DC_EXEC, CMD_ADD_VEHICLE_GROUP);
 }
 
+/**
+ * Create an order backup for the given vehicle.
+ * @param v    The vehicle to make a backup of.
+ * @param user The user that is requesting the backup.
+ * @note Will automatically remove any previous backups of this user.
+ */
 /* static */ void OrderBackup::Backup(const Vehicle *v, uint32 user)
 {
 	/* Don't use reset as that broadcasts over the network to reset the variable,
@@ -95,6 +111,12 @@
 	new OrderBackup(v, user);
 }
 
+/**
+ * Restore the data of this order to the given vehicle.
+ * @param v    The vehicle to restore to.
+ * @param user The user that built the vehicle, thus wants to restore.
+ * @note After restoration the backup will automatically be removed.
+ */
 /* static */ void OrderBackup::Restore(Vehicle *v, uint32 user)
 {
 	OrderBackup *ob;
@@ -106,6 +128,12 @@
 	}
 }
 
+/**
+ * Reset an OrderBackup given a tile and user.
+ * @param tile The tile associated with the OrderBackup.
+ * @param user The user associated with the OrderBackup.
+ * @note Must not be used from the GUI!
+ */
 /* static */ void OrderBackup::ResetOfUser(TileIndex tile, uint32 user)
 {
 	OrderBackup *ob;
@@ -131,6 +159,12 @@
 	return CommandCost();
 }
 
+/**
+ * Reset an user's OrderBackup if needed.
+ * @param user The user associated with the OrderBackup.
+ * @pre _network_server.
+ * @note Must not be used from a command.
+ */
 /* static */ void OrderBackup::ResetUser(uint32 user)
 {
 	assert(_network_server);
@@ -145,6 +179,12 @@
 	}
 }
 
+/**
+ * Reset the OrderBackups from GUI/game logic.
+ * @param tile     The tile of the order backup.
+ * @param from_gui Whether the call came from the GUI, i.e. whether
+ *                 it must be synced over the network.
+ */
 /* static */ void OrderBackup::Reset(TileIndex t, bool from_gui)
 {
 	/* The user has CLIENT_ID_SERVER as default when network play is not active,
@@ -177,6 +217,10 @@
 	}
 }
 
+/**
+ * Clear the group of all backups having this group ID.
+ * @param group The group to clear.
+ */
 /* static */ void OrderBackup::ClearGroup(GroupID group)
 {
 	OrderBackup *ob;
@@ -185,6 +229,13 @@
 	}
 }
 
+/**
+ * Clear/update the (clone) vehicle from an order backup.
+ * @param v The vehicle to clear.
+ * @pre v != NULL
+ * @note If it is not possible to set another vehicle as clone
+ *       "example", then this backed up order will be removed.
+ */
 /* static */ void OrderBackup::ClearVehicle(const Vehicle *v)
 {
 	assert(v != NULL);
--- a/src/order_backup.h
+++ b/src/order_backup.h
@@ -51,77 +51,21 @@
 
 	/** Creation for savegame restoration. */
 	OrderBackup() {}
-
-	/**
-	 * Create an order backup for the given vehicle.
-	 * @param v    The vehicle to make a backup of.
-	 * @param user The user that is requesting the backup.
-	 */
 	OrderBackup(const Vehicle *v, uint32 user);
 
-	/**
-	 * Restore the data of this order to the given vehicle.
-	 * @param v The vehicle to restore to.
-	 */
 	void DoRestore(Vehicle *v);
 
 public:
-	/** Free everything that is allocated. */
 	~OrderBackup();
 
-	/**
-	 * Create an order backup for the given vehicle.
-	 * @param v    The vehicle to make a backup of.
-	 * @param user The user that is requesting the backup.
-	 * @note Will automatically remove any previous backups of this user.
-	 */
 	static void Backup(const Vehicle *v, uint32 user);
-
-	/**
-	 * Restore the data of this order to the given vehicle.
-	 * @param v    The vehicle to restore to.
-	 * @param user The user that built the vehicle, thus wants to restore.
-	 * @note After restoration the backup will automatically be removed.
-	 */
 	static void Restore(Vehicle *v, uint32 user);
 
-	/**
-	 * Reset an OrderBackup given a tile and user.
-	 * @param tile The tile associated with the OrderBackup.
-	 * @param user The user associated with the OrderBackup.
-	 * @note Must not be used from the GUI!
-	 */
 	static void ResetOfUser(TileIndex tile, uint32 user);
-
-	/**
-	 * Reset an user's OrderBackup if needed.
-	 * @param user The user associated with the OrderBackup.
-	 * @pre _network_server.
-	 * @note Must not be used from a command.
-	 */
 	static void ResetUser(uint32 user);
-
-	/**
-	 * Reset the OrderBackups from GUI/game logic.
-	 * @param tile     The tile of the order backup.
-	 * @param from_gui Whether the call came from the GUI, i.e. whether
-	 *                 it must be synced over the network.
-	 */
 	static void Reset(TileIndex tile = INVALID_TILE, bool from_gui = true);
 
-	/**
-	 * Clear the group of all backups having this group ID.
-	 * @param group The group to clear.
-	 */
 	static void ClearGroup(GroupID group);
-
-	/**
-	 * Clear/update the (clone) vehicle from an order backup.
-	 * @param v The vehicle to clear.
-	 * @pre v != NULL
-	 * @note If it is not possible to set another vehicle as clone
-	 *       "example", then this backed up order will be removed.
-	 */
 	static void ClearVehicle(const Vehicle *v);
 };
 
--- a/src/order_base.h
+++ b/src/order_base.h
@@ -53,10 +53,6 @@
 	Order() : refit_cargo(CT_NO_REFIT) {}
 	~Order() {}
 
-	/**
-	 * Create an order based on a packed representation of that order.
-	 * @param packed the packed representation.
-	 */
 	Order(uint32 packed);
 
 	/**
@@ -72,61 +68,15 @@
 	 */
 	inline OrderType GetType() const { return (OrderType)GB(this->type, 0, 4); }
 
-	/**
-	 * 'Free' the order
-	 * @note ONLY use on "current_order" vehicle orders!
-	 */
 	void Free();
 
-	/**
-	 * Makes this order a Go To Station order.
-	 * @param destination the station to go to.
-	 */
 	void MakeGoToStation(StationID destination);
-
-	/**
-	 * Makes this order a Go To Depot order.
-	 * @param destination   the depot to go to.
-	 * @param order         is this order a 'default' order, or an overriden vehicle order?
-	 * @param non_stop_type how to get to the depot?
-	 * @param action        what to do in the depot?
-	 * @param cargo         the cargo type to change to.
-	 * @param subtype       the subtype to change to.
-	 */
 	void MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type = ONSF_NO_STOP_AT_INTERMEDIATE_STATIONS, OrderDepotActionFlags action = ODATF_SERVICE_ONLY, CargoID cargo = CT_NO_REFIT, byte subtype = 0);
-
-	/**
-	 * Makes this order a Go To Waypoint order.
-	 * @param destination the waypoint to go to.
-	 */
 	void MakeGoToWaypoint(StationID destination);
-
-	/**
-	 * Makes this order a Loading order.
-	 * @param ordered is this an ordered stop?
-	 */
 	void MakeLoading(bool ordered);
-
-	/**
-	 * Makes this order a Leave Station order.
-	 */
 	void MakeLeaveStation();
-
-	/**
-	 * Makes this order a Dummy order.
-	 */
 	void MakeDummy();
-
-	/**
-	 * Makes this order an conditional order.
-	 * @param order the order to jump to.
-	 */
 	void MakeConditional(VehicleOrderID order);
-
-	/**
-	 * Makes this order an automatic order.
-	 * @param destination the station to go to.
-	 */
 	void MakeAutomatic(StationID destination);
 
 	/**
@@ -164,12 +114,6 @@
 	 */
 	inline byte GetRefitSubtype() const { return this->refit_subtype; }
 
-	/**
-	 * Make this depot order also a refit order.
-	 * @param cargo   the cargo type to change to.
-	 * @param subtype the subtype to change to.
-	 * @pre IsType(OT_GOTO_DEPOT).
-	 */
 	void SetRefit(CargoID cargo, byte subtype = 0);
 
 	/** How must the consist be loaded? */
@@ -225,38 +169,11 @@
 		return true;
 	}
 
-	/**
-	 * Assign the given order to this one.
-	 * @param other the data to copy (except next pointer).
-	 */
 	void AssignOrder(const Order &other);
-
-	/**
-	 * Does this order have the same type, flags and destination?
-	 * @param other the second order to compare to.
-	 * @return true if the type, flags and destination match.
-	 */
 	bool Equals(const Order &other) const;
 
-	/**
-	 * Pack this order into a 32 bits integer, or actually only
-	 * the type, flags and destination.
-	 * @return the packed representation.
-	 * @note unpacking is done in the constructor.
-	 */
 	uint32 Pack() const;
-
-	/**
-	 * Pack this order into a 16 bits integer as close to the TTD
-	 * representation as possible.
-	 * @return the TTD-like packed representation.
-	 */
 	uint16 MapOldOrder() const;
-
-	/**
-	 * Converts this order from an old savegame's version;
-	 * it moves all bits to the new location.
-	 */
 	void ConvertFromOldSavegame();
 };
 
@@ -296,11 +213,6 @@
 	/** Destructor. Invalidates OrderList for re-usage by the pool. */
 	~OrderList() {}
 
-	/**
-	 * Recomputes everything.
-	 * @param chain first order in the chain
-	 * @param v one of vehicle that is using this orderlist
-	 */
 	void Initialize(Order *chain, Vehicle *v);
 
 	/**
@@ -309,11 +221,6 @@
 	 */
 	inline Order *GetFirstOrder() const { return this->first; }
 
-	/**
-	 * Get a certain order of the order chain.
-	 * @param index zero-based index of the order within the chain.
-	 * @return the order at position index.
-	 */
 	Order *GetOrderAt(int index) const;
 
 	/**
@@ -334,24 +241,8 @@
 	 */
 	inline VehicleOrderID GetNumManualOrders() const { return this->num_manual_orders; }
 
-	/**
-	 * Insert a new order into the order chain.
-	 * @param new_order is the order to insert into the chain.
-	 * @param index is the position where the order is supposed to be inserted.
-	 */
 	void InsertOrderAt(Order *new_order, int index);
-
-	/**
-	 * Remove an order from the order list and delete it.
-	 * @param index is the position of the order which is to be deleted.
-	 */
 	void DeleteOrderAt(int index);
-
-	/**
-	 * Move an order to another position within the order list.
-	 * @param from is the zero-based position of the order to move.
-	 * @param to is the zero-based position where the order is moved to.
-	 */
 	void MoveOrder(int from, int to);
 
 	/**
@@ -372,17 +263,7 @@
 	 */
 	inline uint GetNumVehicles() const { return this->num_vehicles; }
 
-	/**
-	 * Checks whether a vehicle is part of the shared vehicle chain.
-	 * @param v is the vehicle to search in the shared vehicle chain.
-	 */
 	bool IsVehicleInSharedOrdersList(const Vehicle *v) const;
-
-	/**
-	 * Gets the position of the given vehicle within the shared order vehicle list.
-	 * @param v is the vehicle of which to get the position
-	 * @return position of v within the shared vehicle chain.
-	 */
 	int GetPositionInSharedOrderList(const Vehicle *v) const;
 
 	/**
@@ -393,17 +274,8 @@
 	 */
 	inline void AddVehicle(Vehicle *v) { ++this->num_vehicles; }
 
-	/**
-	 * Removes the vehicle from the shared order list.
-	 * @note This is supposed to be called when the vehicle is still in the chain
-	 * @param v vehicle to remove from the list
-	 */
 	void RemoveVehicle(Vehicle *v);
 
-	/**
-	 * Checks whether all orders of the list have a filled timetable.
-	 * @return whether all orders have a filled timetable.
-	 */
 	bool IsCompleteTimetable() const;
 
 	/**
@@ -424,16 +296,8 @@
 	 */
 	void UpdateOrderTimetable(Ticks delta) { this->timetable_duration += delta; }
 
-	/**
-	 * Free a complete order chain.
-	 * @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList.
-	 * @note do not use on "current_order" vehicle orders!
-	 */
 	void FreeChain(bool keep_orderlist = false);
 
-	/**
-	 * Checks for internal consistency of order list. Triggers assertion if something is wrong.
-	 */
 	void DebugCheckSanity() const;
 };
 
--- a/src/order_cmd.cpp
+++ b/src/order_cmd.cpp
@@ -42,6 +42,10 @@
 OrderListPool _orderlist_pool("OrderList");
 INSTANTIATE_POOL_METHODS(OrderList)
 
+/**
+ * 'Free' the order
+ * @note ONLY use on "current_order" vehicle orders!
+ */
 void Order::Free()
 {
 	this->type  = OT_NOTHING;
@@ -50,6 +54,10 @@
 	this->next  = NULL;
 }
 
+/**
+ * Makes this order a Go To Station order.
+ * @param destination the station to go to.
+ */
 void Order::MakeGoToStation(StationID destination)
 {
 	this->type = OT_GOTO_STATION;
@@ -57,6 +65,15 @@
 	this->dest = destination;
 }
 
+/**
+ * Makes this order a Go To Depot order.
+ * @param destination   the depot to go to.
+ * @param order         is this order a 'default' order, or an overriden vehicle order?
+ * @param non_stop_type how to get to the depot?
+ * @param action        what to do in the depot?
+ * @param cargo         the cargo type to change to.
+ * @param subtype       the subtype to change to.
+ */
 void Order::MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type, OrderDepotActionFlags action, CargoID cargo, byte subtype)
 {
 	this->type = OT_GOTO_DEPOT;
@@ -67,6 +84,10 @@
 	this->SetRefit(cargo, subtype);
 }
 
+/**
+ * Makes this order a Go To Waypoint order.
+ * @param destination the waypoint to go to.
+ */
 void Order::MakeGoToWaypoint(StationID destination)
 {
 	this->type = OT_GOTO_WAYPOINT;
@@ -74,24 +95,38 @@
 	this->dest = destination;
 }
 
+/**
+ * Makes this order a Loading order.
+ * @param ordered is this an ordered stop?
+ */
 void Order::MakeLoading(bool ordered)
 {
 	this->type = OT_LOADING;
 	if (!ordered) this->flags = 0;
 }
 
+/**
+ * Makes this order a Leave Station order.
+ */
 void Order::MakeLeaveStation()
 {
 	this->type = OT_LEAVESTATION;
 	this->flags = 0;
 }
 
+/**
+ * Makes this order a Dummy order.
+ */
 void Order::MakeDummy()
 {
 	this->type = OT_DUMMY;
 	this->flags = 0;
 }
 
+/**
+ * Makes this order an conditional order.
+ * @param order the order to jump to.
+ */
 void Order::MakeConditional(VehicleOrderID order)
 {
 	this->type = OT_CONDITIONAL;
@@ -99,18 +134,33 @@
 	this->dest = 0;
 }
 
+/**
+ * Makes this order an automatic order.
+ * @param destination the station to go to.
+ */
 void Order::MakeAutomatic(StationID destination)
 {
 	this->type = OT_AUTOMATIC;
 	this->dest = destination;
 }
 
+/**
+ * Make this depot order also a refit order.
+ * @param cargo   the cargo type to change to.
+ * @param subtype the subtype to change to.
+ * @pre IsType(OT_GOTO_DEPOT).
+ */
 void Order::SetRefit(CargoID cargo, byte subtype)
 {
 	this->refit_cargo = cargo;
 	this->refit_subtype = subtype;
 }
 
+/**
+ * Does this order have the same type, flags and destination?
+ * @param other the second order to compare to.
+ * @return true if the type, flags and destination match.
+ */
 bool Order::Equals(const Order &other) const
 {
 	/* In case of go to nearest depot orders we need "only" compare the flags
@@ -128,11 +178,22 @@
 	return this->type == other.type && this->flags == other.flags && this->dest == other.dest;
 }
 
+/**
+ * Pack this order into a 32 bits integer, or actually only
+ * the type, flags and destination.
+ * @return the packed representation.
+ * @note unpacking is done in the constructor.
+ */
 uint32 Order::Pack() const
 {
 	return this->dest << 16 | this->flags << 8 | this->type;
 }
 
+/**
+ * Pack this order into a 16 bits integer as close to the TTD
+ * representation as possible.
+ * @return the TTD-like packed representation.
+ */
 uint16 Order::MapOldOrder() const
 {
 	uint16 order = this->GetType();
@@ -155,6 +216,10 @@
 	return order;
 }
 
+/**
+ * Create an order based on a packed representation of that order.
+ * @param packed the packed representation.
+ */
 Order::Order(uint32 packed)
 {
 	this->type    = (OrderType)GB(packed,  0,  8);
@@ -191,6 +256,7 @@
  *
  * Assign data to an order (from another order)
  *   This function makes sure that the index is maintained correctly
+ * @param other the data to copy (except next pointer).
  *
  */
 void Order::AssignOrder(const Order &other)
@@ -206,6 +272,11 @@
 	this->travel_time = other.travel_time;
 }
 
+/**
+ * Recomputes everything.
+ * @param chain first order in the chain
+ * @param v one of vehicle that is using this orderlist
+ */
 void OrderList::Initialize(Order *chain, Vehicle *v)
 {
 	this->first = chain;
@@ -230,6 +301,11 @@
 	for (const Vehicle *u = v->NextShared(); u != NULL; u = u->NextShared()) ++this->num_vehicles;
 }
 
+/**
+ * Free a complete order chain.
+ * @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList.
+ * @note do not use on "current_order" vehicle orders!
+ */
 void OrderList::FreeChain(bool keep_orderlist)
 {
 	Order *next;
@@ -248,6 +324,11 @@
 	}
 }
 
+/**
+ * Get a certain order of the order chain.
+ * @param index zero-based index of the order within the chain.
+ * @return the order at position index.
+ */
 Order *OrderList::GetOrderAt(int index) const
 {
 	if (index < 0) return NULL;
@@ -260,6 +341,11 @@
 	return order;
 }
 
+/**
+ * Insert a new order into the order chain.
+ * @param new_order is the order to insert into the chain.
+ * @param index is the position where the order is supposed to be inserted.
+ */
 void OrderList::InsertOrderAt(Order *new_order, int index)
 {
 	if (this->first == NULL) {
@@ -285,6 +371,10 @@
 }
 
 
+/**
+ * Remove an order from the order list and delete it.
+ * @param index is the position of the order which is to be deleted.
+ */
 void OrderList::DeleteOrderAt(int index)
 {
 	if (index >= this->num_orders) return;
@@ -305,6 +395,11 @@
 	delete to_remove;
 }
 
+/**
+ * Move an order to another position within the order list.
+ * @param from is the zero-based position of the order to move.
+ * @param to is the zero-based position where the order is moved to.
+ */
 void OrderList::MoveOrder(int from, int to)
 {
 	if (from >= this->num_orders || to >= this->num_orders || from == to) return;
@@ -332,12 +427,21 @@
 	}
 }
 
+/**
+ * Removes the vehicle from the shared order list.
+ * @note This is supposed to be called when the vehicle is still in the chain
+ * @param v vehicle to remove from the list
+ */
 void OrderList::RemoveVehicle(Vehicle *v)
 {
 	--this->num_vehicles;
 	if (v == this->first_shared) this->first_shared = v->NextShared();
 }
 
+/**
+ * Checks whether a vehicle is part of the shared vehicle chain.
+ * @param v is the vehicle to search in the shared vehicle chain.
+ */
 bool OrderList::IsVehicleInSharedOrdersList(const Vehicle *v) const
 {
 	for (const Vehicle *v_shared = this->first_shared; v_shared != NULL; v_shared = v_shared->NextShared()) {
@@ -347,6 +451,11 @@
 	return false;
 }
 
+/**
+ * Gets the position of the given vehicle within the shared order vehicle list.
+ * @param v is the vehicle of which to get the position
+ * @return position of v within the shared vehicle chain.
+ */
 int OrderList::GetPositionInSharedOrderList(const Vehicle *v) const
 {
 	int count = 0;
@@ -354,6 +463,10 @@
 	return count;
 }
 
+/**
+ * Checks whether all orders of the list have a filled timetable.
+ * @return whether all orders have a filled timetable.
+ */
 bool OrderList::IsCompleteTimetable() const
 {
 	for (Order *o = this->first; o != NULL; o = o->next) {
@@ -364,6 +477,9 @@
 	return true;
 }
 
+/**
+ * Checks for internal consistency of order list. Triggers assertion if something is wrong.
+ */
 void OrderList::DebugCheckSanity() const
 {
 	VehicleOrderID check_num_orders = 0;
@@ -1524,6 +1640,13 @@
 	}
 }
 
+/**
+ * Clamp the service interval to the correct min/max. The actual min/max values
+ * depend on whether it's in percent or days.
+ * @param interval proposed service interval
+ * @param company_id the owner of the vehicle
+ * @return Clamped service interval
+ */
 uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id)
 {
 	return (Company::Get(company_id)->settings.vehicle.servint_ispercent) ? Clamp(interval, MIN_SERVINT_PERCENT, MAX_SERVINT_PERCENT) : Clamp(interval, MIN_SERVINT_DAYS, MAX_SERVINT_DAYS);
--- a/src/order_func.h
+++ b/src/order_func.h
@@ -32,13 +32,6 @@
 #define MIN_SERVINT_DAYS    30
 #define MAX_SERVINT_DAYS   800
 
-/**
- * Clamp the service interval to the correct min/max. The actual min/max values
- * depend on whether it's in percent or days.
- * @param interval proposed service interval
- * @param company_id the owner of the vehicle
- * @return Clamped service interval
- */
 uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id);
 
 #endif /* ORDER_FUNC_H */
--- a/src/rail.cpp
+++ b/src/rail.cpp
@@ -149,6 +149,9 @@
 	TRACKDIR_BIT_X_NE | TRACKDIR_BIT_Y_SE, ///< 30 SLOPE_STEEP_E -> inclined for diagonal track
 };
 
+/**
+ * Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile.
+ */
 RailType GetTileRailType(TileIndex tile)
 {
 	switch (GetTileType(tile)) {
@@ -174,16 +177,34 @@
 	return INVALID_RAILTYPE;
 }
 
+/**
+ * Finds out if a company has a certain railtype available
+ * @param company the company in question
+ * @param railtype requested RailType
+ * @return true if company has requested RailType available
+ */
 bool HasRailtypeAvail(const CompanyID company, const RailType railtype)
 {
 	return HasBit(Company::Get(company)->avail_railtypes, railtype);
 }
 
+/**
+ * Validate functions for rail building.
+ * @param rail the railtype to check.
+ * @return true if the current company may build the rail.
+ */
 bool ValParamRailtype(const RailType rail)
 {
 	return rail < RAILTYPE_END && HasRailtypeAvail(_current_company, rail);
 }
 
+/**
+ * Returns the "best" railtype a company can build.
+ * As the AI doesn't know what the BEST one is, we have our own priority list
+ * here. When adding new railtypes, modify this function
+ * @param company the company "in action"
+ * @return The "best" railtype a company has available
+ */
 RailType GetBestRailtype(const CompanyID company)
 {
 	if (HasRailtypeAvail(company, RAILTYPE_MAGLEV)) return RAILTYPE_MAGLEV;
@@ -226,6 +247,11 @@
 	return rts == current ? rts : AddDateIntroducedRailTypes(rts, date);
 }
 
+/**
+ * Get the rail types the given company can build.
+ * @param c the company to get the rail types for.
+ * @return the rail types.
+ */
 RailTypes GetCompanyRailtypes(CompanyID company)
 {
 	RailTypes rts = RAILTYPES_NONE;
@@ -248,6 +274,11 @@
 	return AddDateIntroducedRailTypes(rts, _date);
 }
 
+/**
+ * Get the rail type for a given label.
+ * @param label the railtype label.
+ * @return the railtype.
+ */
 RailType GetRailTypeByLabel(RailTypeLabel label)
 {
 	/* Loop through each rail type until the label is found */
--- a/src/rail.h
+++ b/src/rail.h
@@ -360,59 +360,18 @@
 Foundation GetRailFoundation(Slope tileh, TrackBits bits);
 
 
-/**
- * Finds out if a company has a certain railtype available
- * @param company the company in question
- * @param railtype requested RailType
- * @return true if company has requested RailType available
- */
 bool HasRailtypeAvail(const CompanyID company, const RailType railtype);
-
-/**
- * Validate functions for rail building.
- * @param rail the railtype to check.
- * @return true if the current company may build the rail.
- */
 bool ValParamRailtype(const RailType rail);
 
-/**
- * Returns the "best" railtype a company can build.
- * As the AI doesn't know what the BEST one is, we have our own priority list
- * here. When adding new railtypes, modify this function
- * @param company the company "in action"
- * @return The "best" railtype a company has available
- */
-RailType GetBestRailtype(const CompanyID company);
-
 RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date);
 
-/**
- * Get the rail types the given company can build.
- * @param c the company to get the rail types for.
- * @return the rail types.
- */
+RailType GetBestRailtype(const CompanyID company);
 RailTypes GetCompanyRailtypes(const CompanyID c);
 
-/**
- * Get the rail type for a given label.
- * @param label the railtype label.
- * @return the railtype.
- */
 RailType GetRailTypeByLabel(RailTypeLabel label);
 
-/**
- * Reset all rail type information to its default values.
- */
 void ResetRailTypes();
-
-/**
- * Resolve sprites of custom rail types
- */
 void InitRailTypes();
-
-/**
- * Allocate a new rail type label
- */
 RailType AllocateRailType(RailTypeLabel label);
 
 #endif /* RAIL_H */
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -45,7 +45,7 @@
 assert_compile(sizeof(_original_railtypes) <= sizeof(_railtypes));
 
 /**
- * Initialize rail type information.
+ * Reset all rail type information to its default values.
  */
 void ResetRailTypes()
 {
@@ -76,6 +76,9 @@
 	}
 }
 
+/**
+ * Resolve sprites of custom rail types
+ */
 void InitRailTypes()
 {
 	for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) {
@@ -84,6 +87,9 @@
 	}
 }
 
+/**
+ * Allocate a new rail type label
+ */
 RailType AllocateRailType(RailTypeLabel label)
 {
 	for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) {
--- a/src/rail_map.h
+++ b/src/rail_map.h
@@ -490,9 +490,6 @@
 }
 
 
-/**
- * Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile.
- */
 RailType GetTileRailType(TileIndex tile);
 
 /** The ground 'under' the rail */
--- a/src/road.cpp
+++ b/src/road.cpp
@@ -36,6 +36,12 @@
 		GetFoundationSlope(tile, NULL) == SLOPE_FLAT);
 }
 
+/**
+ * Clean up unneccesary RoadBits of a planed tile.
+ * @param tile current tile
+ * @param org_rb planed RoadBits
+ * @return optimised RoadBits
+ */
 RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb)
 {
 	if (!IsValidTile(tile)) return ROAD_NONE;
@@ -91,6 +97,12 @@
 	return org_rb;
 }
 
+/**
+ * Finds out, whether given company has all given RoadTypes available
+ * @param company ID of company
+ * @param rts RoadTypes to test
+ * @return true if company has all requested RoadTypes available
+ */
 bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts)
 {
 	RoadTypes avail_roadtypes;
@@ -105,11 +117,21 @@
 	return (rts & ~avail_roadtypes) == 0;
 }
 
+/**
+ * Validate functions for rail building.
+ * @param rt road type to check.
+ * @return true if the current company may build the road.
+ */
 bool ValParamRoadType(const RoadType rt)
 {
 	return HasRoadTypesAvail(_current_company, RoadTypeToRoadTypes(rt));
 }
 
+/**
+ * Get the road types the given company can build.
+ * @param company the company to get the roadtypes for.
+ * @return the road types.
+ */
 RoadTypes GetCompanyRoadtypes(CompanyID company)
 {
 	RoadTypes rt = ROADTYPES_NONE;
--- a/src/road_func.h
+++ b/src/road_func.h
@@ -148,26 +148,8 @@
 	return a == AXIS_X ? ROAD_X : ROAD_Y;
 }
 
-/**
- * Finds out, whether given company has all given RoadTypes available
- * @param company ID of company
- * @param rts RoadTypes to test
- * @return true if company has all requested RoadTypes available
- */
 bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts);
-
-/**
- * Validate functions for rail building.
- * @param rt road type to check.
- * @return true if the current company may build the road.
- */
 bool ValParamRoadType(const RoadType rt);
-
-/**
- * Get the road types the given company can build.
- * @param company the company to get the roadtypes for.
- * @return the road types.
- */
 RoadTypes GetCompanyRoadtypes(const CompanyID company);
 
 void UpdateLevelCrossing(TileIndex tile, bool sound = true);
--- a/src/road_internal.h
+++ b/src/road_internal.h
@@ -15,21 +15,10 @@
 #include "tile_cmd.h"
 #include "road_type.h"
 
-/**
- * Clean up unneccesary RoadBits of a planed tile.
- * @param tile current tile
- * @param org_rb planed RoadBits
- * @return optimised RoadBits
- */
 RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb);
 
 CommandCost CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, Owner owner, RoadType rt, DoCommandFlag flags, bool town_check = true);
 
-/**
- * Draw the catenary for tram road bits
- * @param ti   information about the tile (position, slope)
- * @param tram the roadbits to draw the catenary for
- */
 void DrawTramCatenary(const TileInfo *ti, RoadBits tram);
 
 #endif /* ROAD_INTERNAL_H */
--- a/src/road_map.cpp
+++ b/src/road_map.cpp
@@ -14,6 +14,22 @@
 #include "tunnelbridge_map.h"
 
 
+/**
+ * Returns the RoadBits on an arbitrary tile
+ * Special behaviour:
+ * - road depots: entrance is treated as road piece
+ * - road tunnels: entrance is treated as road piece
+ * - bridge ramps: start of the ramp is treated as road piece
+ * - bridge middle parts: bridge itself is ignored
+ *
+ * If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y
+ * for bridge ramps and tunnel entrances is returned depending
+ * on the orientation of the tunnel or bridge.
+ * @param tile the tile to get the road bits for
+ * @param rt   the road type to get the road bits form
+ * @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges.
+ * @return the road bits of the given tile
+ */
 RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance)
 {
 	if (!HasTileRoadType(tile, rt)) return ROAD_NONE;
--- a/src/road_map.h
+++ b/src/road_map.h
@@ -536,22 +536,6 @@
 }
 
 
-/**
- * Returns the RoadBits on an arbitrary tile
- * Special behaviour:
- * - road depots: entrance is treated as road piece
- * - road tunnels: entrance is treated as road piece
- * - bridge ramps: start of the ramp is treated as road piece
- * - bridge middle parts: bridge itself is ignored
- *
- * If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y
- * for bridge ramps and tunnel entrances is returned depending
- * on the orientation of the tunnel or bridge.
- * @param tile the tile to get the road bits for
- * @param rt   the road type to get the road bits form
- * @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges.
- * @return the road bits of the given tile
- */
 RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance = false);
 
 
--- a/src/saveload/order_sl.cpp
+++ b/src/saveload/order_sl.cpp
@@ -17,6 +17,10 @@
 
 #include "saveload.h"
 
+/**
+ * Converts this order from an old savegame's version;
+ * it moves all bits to the new location.
+ */
 void Order::ConvertFromOldSavegame()
 {
 	uint8 old_flags = this->flags;
--- a/src/signs.cpp
+++ b/src/signs.cpp
@@ -22,11 +22,15 @@
 SignPool _sign_pool("Sign");
 INSTANTIATE_POOL_METHODS(Sign)
 
+/**
+ * Creates a new sign
+ */
 Sign::Sign(Owner owner)
 {
 	this->owner = owner;
 }
 
+/** Destroy the sign */
 Sign::~Sign()
 {
 	free(this->name);
--- a/src/signs_base.h
+++ b/src/signs_base.h
@@ -28,12 +28,7 @@
 	byte         z;
 	OwnerByte    owner; // placed by this company. Anyone can delete them though. OWNER_NONE for gray signs from old games.
 
-	/**
-	 * Creates a new sign
-	 */
 	Sign(Owner owner = INVALID_OWNER);
-
-	/** Destroy the sign */
 	~Sign();
 
 	void UpdateVirtCoord();
--- a/src/station.cpp
+++ b/src/station.cpp
@@ -155,6 +155,11 @@
 	this->build_date = _date;
 }
 
+/**
+ * Marks the tiles of the station as dirty.
+ *
+ * @ingroup dirty
+ */
 void Station::MarkTilesDirty(bool cargo_change) const
 {
 	TileIndex tile = this->train_station.tile;
--- a/src/station_base.h
+++ b/src/station_base.h
@@ -199,11 +199,6 @@
 
 	void AddFacility(StationFacility new_facility_bit, TileIndex facil_xy);
 
-	/**
-	 * Marks the tiles of the station as dirty.
-	 *
-	 * @ingroup dirty
-	 */
 	void MarkTilesDirty(bool cargo_change) const;
 
 	void UpdateVirtCoord();
--- a/src/string.cpp
+++ b/src/string.cpp
@@ -48,6 +48,20 @@
 	return min((int)diff, vsnprintf(str, diff + 1, format, ap));
 }
 
+/**
+ * Appends characters from one string to another.
+ *
+ * Appends the source string to the destination string with respect of the
+ * terminating null-character and the maximum size of the destination
+ * buffer.
+ *
+ * @note usage ttd_strlcat(dst, src, lengthof(dst));
+ * @note lengthof() applies only to fixed size arrays
+ *
+ * @param dst The buffer containing the target string
+ * @param src The buffer containing the string to append
+ * @param size The maximum size of the destination buffer
+ */
 void ttd_strlcat(char *dst, const char *src, size_t size)
 {
 	assert(size > 0);
@@ -60,6 +74,20 @@
 }
 
 
+/**
+ * Copies characters from one buffer to another.
+ *
+ * Copies the source string to the destination buffer with respect of the
+ * terminating null-character and the maximum size of the destination
+ * buffer.
+ *
+ * @note usage ttd_strlcpy(dst, src, lengthof(dst));
+ * @note lengthof() applies only to fixed size arrays
+ *
+ * @param dst The destination buffer
+ * @param src The buffer containing the string to copy
+ * @param size The maximum size of the destination buffer
+ */
 void ttd_strlcpy(char *dst, const char *src, size_t size)
 {
 	assert(size > 0);
@@ -70,6 +98,22 @@
 }
 
 
+/**
+ * Appends characters from one string to another.
+ *
+ * Appends the source string to the destination string with respect of the
+ * terminating null-character and and the last pointer to the last element
+ * in the destination buffer. If the last pointer is set to NULL no
+ * boundary check is performed.
+ *
+ * @note usage: strecat(dst, src, lastof(dst));
+ * @note lastof() applies only to fixed size arrays
+ *
+ * @param dst The buffer containing the target string
+ * @param src The buffer containing the string to append
+ * @param last The pointer to the last element of the destination buffer
+ * @return The pointer to the terminating null-character in the destination buffer
+ */
 char *strecat(char *dst, const char *src, const char *last)
 {
 	assert(dst <= last);
@@ -82,6 +126,22 @@
 }
 
 
+/**
+ * Copies characters from one buffer to another.
+ *
+ * Copies the source string to the destination buffer with respect of the
+ * terminating null-character and the last pointer to the last element in
+ * the destination buffer. If the last pointer is set to NULL no boundary
+ * check is performed.
+ *
+ * @note usage: strecpy(dst, src, lastof(dst));
+ * @note lastof() applies only to fixed size arrays
+ *
+ * @param dst The destination buffer
+ * @param src The buffer containing the string to copy
+ * @param last The pointer to the last element of the destination buffer
+ * @return The pointer to the terminating null-character in the destination buffer
+ */
 char *strecpy(char *dst, const char *src, const char *last)
 {
 	assert(dst <= last);
@@ -115,6 +175,14 @@
 }
 
 
+/**
+ * Scans the string for valid characters and if it finds invalid ones,
+ * replaces them with a question mark '?' (if not ignored)
+ * @param str the string to validate
+ * @param last the last valid character of str
+ * @param allow_newlines whether newlines should be allowed or ignored
+ * @param ignore whether to ignore or replace with a question mark
+ */
 void str_validate(char *str, const char *last, bool allow_newlines, bool ignore)
 {
 	/* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */
@@ -169,6 +237,13 @@
 	*dst = '\0';
 }
 
+/**
+ * Checks whether the given string is valid, i.e. contains only
+ * valid (printable) characters and is properly terminated.
+ * @param str  The string to validate.
+ * @param last The last character of the string, i.e. the string
+ *             must be terminated here or earlier.
+ */
 bool StrValid(const char *str, const char *last)
 {
 	/* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */
@@ -193,6 +268,7 @@
 	return *str == '\0';
 }
 
+/** Scans the string for colour codes and strips them */
 void str_strip_colours(char *str)
 {
 	char *dst = str;
--- a/src/string_func.h
+++ b/src/string_func.h
@@ -29,101 +29,20 @@
 #include "core/bitmath_func.hpp"
 #include "string_type.h"
 
-/**
- * Appends characters from one string to another.
- *
- * Appends the source string to the destination string with respect of the
- * terminating null-character and the maximum size of the destination
- * buffer.
- *
- * @note usage ttd_strlcat(dst, src, lengthof(dst));
- * @note lengthof() applies only to fixed size arrays
- *
- * @param dst The buffer containing the target string
- * @param src The buffer containing the string to append
- * @param size The maximum size of the destination buffer
- */
 void ttd_strlcat(char *dst, const char *src, size_t size);
-
-/**
- * Copies characters from one buffer to another.
- *
- * Copies the source string to the destination buffer with respect of the
- * terminating null-character and the maximum size of the destination
- * buffer.
- *
- * @note usage ttd_strlcpy(dst, src, lengthof(dst));
- * @note lengthof() applies only to fixed size arrays
- *
- * @param dst The destination buffer
- * @param src The buffer containing the string to copy
- * @param size The maximum size of the destination buffer
- */
 void ttd_strlcpy(char *dst, const char *src, size_t size);
 
-/**
- * Appends characters from one string to another.
- *
- * Appends the source string to the destination string with respect of the
- * terminating null-character and and the last pointer to the last element
- * in the destination buffer. If the last pointer is set to NULL no
- * boundary check is performed.
- *
- * @note usage: strecat(dst, src, lastof(dst));
- * @note lastof() applies only to fixed size arrays
- *
- * @param dst The buffer containing the target string
- * @param src The buffer containing the string to append
- * @param last The pointer to the last element of the destination buffer
- * @return The pointer to the terminating null-character in the destination buffer
- */
 char *strecat(char *dst, const char *src, const char *last);
-
-/**
- * Copies characters from one buffer to another.
- *
- * Copies the source string to the destination buffer with respect of the
- * terminating null-character and the last pointer to the last element in
- * the destination buffer. If the last pointer is set to NULL no boundary
- * check is performed.
- *
- * @note usage: strecpy(dst, src, lastof(dst));
- * @note lastof() applies only to fixed size arrays
- *
- * @param dst The destination buffer
- * @param src The buffer containing the string to copy
- * @param last The pointer to the last element of the destination buffer
- * @return The pointer to the terminating null-character in the destination buffer
- */
 char *strecpy(char *dst, const char *src, const char *last);
 
 int CDECL seprintf(char *str, const char *last, const char *format, ...) WARN_FORMAT(3, 4);
 
 char *CDECL str_fmt(const char *str, ...) WARN_FORMAT(1, 2);
 
-/**
- * Scans the string for valid characters and if it finds invalid ones,
- * replaces them with a question mark '?' (if not ignored)
- * @param str the string to validate
- * @param last the last valid character of str
- * @param allow_newlines whether newlines should be allowed or ignored
- * @param ignore whether to ignore or replace with a question mark
- */
 void str_validate(char *str, const char *last, bool allow_newlines = false, bool ignore = false);
-
-/** Scans the string for colour codes and strips them */
 void str_strip_colours(char *str);
-
-/** Convert the given string to lowercase, only works with ASCII! */
 void strtolower(char *str);
 
-/**
- * Checks whether the given string is valid, i.e. contains only
- * valid (printable) characters and is properly terminated.
- * @param str  The string to validate.
- * @param last The last character of the string, i.e. the string
- *             must be terminated here or earlier.
- */
 bool StrValid(const char *str, const char *last);
 
 /**
@@ -152,16 +71,8 @@
 	return t - str;
 }
 
-/** Convert the md5sum number to a 'hexadecimal' string, return next pos in buffer */
 char *md5sumToString(char *buf, const char *last, const uint8 md5sum[16]);
 
-/**
- * Only allow certain keys. You can define the filter to be used. This makes
- *  sure no invalid keys can get into an editbox, like BELL.
- * @param key character to be checked
- * @param afilter the filter to use
- * @return true or false depending if the character is printable/valid or not
- */
 bool IsValidChar(WChar key, CharSetFilter afilter);
 
 size_t Utf8Decode(WChar *c, const char *s);