(svn r21843) -Codechange: move documentation towards the code to make it more likely to be updates [t-z].

7 files changed, 77 insertions, 88 deletions

diff --git a/src/tilearea.cpp b/src/tilearea.cpp
index 498714ec0..7a5bf9f44 100644
--- a/src/tilearea.cpp
+++ b/src/tilearea.cpp
@@ -104,6 +104,11 @@ void TileArea::ClampToMap()
 	this->h = min(this->h, MapSizeY() - TileY(this->tile));
 }
 
+/**
+ * Construct the iterator.
+ * @param begin Tile from where to begin iterating.
+ * @param end   Tile where to end the iterating.
+ */
 DiagonalTileIterator::DiagonalTileIterator(TileIndex corner1, TileIndex corner2) : TileIterator(corner2), base_x(TileX(corner2)), base_y(TileY(corner2)), a_cur(0), b_cur(0)
 {
 	assert(corner1 < MapSize());
@@ -135,6 +140,9 @@ DiagonalTileIterator::DiagonalTileIterator(TileIndex corner1, TileIndex corner2)
 	}
 }
 
+/**
+ * Move ourselves to the next tile in the rectange on the map.
+ */
 TileIterator &DiagonalTileIterator::operator++()
 {
 	assert(this->tile != INVALID_TILE);
diff --git a/src/tilearea_type.h b/src/tilearea_type.h
index 23813eeb8..219416acf 100644
--- a/src/tilearea_type.h
+++ b/src/tilearea_type.h
@@ -137,16 +137,8 @@ private:
 	int a_max, b_max;    ///< The (rotated) x and y coordinates of the end of the iteration.
 
 public:
-	/**
-	 * Construct the iterator.
-	 * @param begin Tile from where to begin iterating.
-	 * @param end   Tile where to end the iterating.
-	 */
 	DiagonalTileIterator(TileIndex begin, TileIndex end);
 
-	/**
-	 * Move ourselves to the next tile in the rectange on the map.
-	 */
 	TileIterator& operator ++();
 };
 
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index 04521043c..397c13a99 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -96,6 +96,12 @@ void VehicleServiceInDepot(Vehicle *v)
 	SetWindowDirty(WC_VEHICLE_DETAILS, v->index); // ensure that last service date and reliability are updated
 }
 
+/**
+ * Check if the vehicle needs to go to a depot in near future (if a opportunity presents itself) for service or replacement.
+ *
+ * @see NeedsAutomaticServicing()
+ * @return true if the vehicle should go to a depot if a opportunity presents itself.
+ */
 bool Vehicle::NeedsServicing() const
 {
 	/* Stopped or crashed vehicles will not move, as such making unmovable
@@ -156,6 +162,11 @@ bool Vehicle::NeedsServicing() const
 	return pending_replace;
 }
 
+/**
+ * Checks if the current order should be interupted for a service-in-depot-order.
+ * @see NeedsServicing()
+ * @return true if the current order should be interupted.
+ */
 bool Vehicle::NeedsAutomaticServicing() const
 {
 	if (_settings_game.order.gotodepot && this->HasDepotOrder()) return false;
@@ -657,6 +668,7 @@ void Vehicle::HandlePathfindingResult(bool path_found)
 	}
 }
 
+/** Destroy all stuff that (still) needs the virtual functions to work properly */
 void Vehicle::PreDestructor()
 {
 	if (CleaningPool()) return;
@@ -1026,6 +1038,12 @@ void CheckVehicleBreakdown(Vehicle *v)
 	}
 }
 
+/**
+ * Handle all of the aspects of a vehicle breakdown
+ * This includes adding smoke and sounds, and ending the breakdown when appropriate.
+ * @return true iff the vehicle is stopped because of a breakdown
+ * @note This function always returns false for aircraft, since these never stop for breakdowns
+ */
 bool Vehicle::HandleBreakdown()
 {
 	/* Possible states for Vehicle::breakdown_ctr
@@ -1393,6 +1411,13 @@ VehicleEnterTileStatus VehicleEnterTile(Vehicle *v, TileIndex tile, int x, int y
 	return _tile_type_procs[GetTileType(tile)]->vehicle_enter_tile_proc(v, tile, x, y);
 }
 
+/**
+ * Initializes the structure. Vehicle unit numbers are supposed not to change after
+ * struct initialization, except after each call to this->NextID() the returned value
+ * is assigned to a vehicle.
+ * @param type type of vehicle
+ * @param owner owner of vehicles
+ */
 FreeUnitIDGenerator::FreeUnitIDGenerator(VehicleType type, CompanyID owner) : cache(NULL), maxid(0), curid(0)
 {
 	/* Find maximum */
@@ -1418,6 +1443,7 @@ FreeUnitIDGenerator::FreeUnitIDGenerator(VehicleType type, CompanyID owner) : ca
 	}
 }
 
+/** Returns next free UnitID. Supposes the last returned value was assigned to a vehicle. */
 UnitID FreeUnitIDGenerator::NextID()
 {
 	if (this->maxid <= this->curid) return ++this->curid;
@@ -1658,11 +1684,22 @@ static PaletteID GetEngineColourMap(EngineID engine_type, CompanyID company, Eng
 	return map;
 }
 
+/**
+ * Get the colour map for an engine. This used for unbuilt engines in the user interface.
+ * @param engine_type ID of engine
+ * @param company ID of company
+ * @return A ready-to-use palette modifier
+ */
 PaletteID GetEnginePalette(EngineID engine_type, CompanyID company)
 {
 	return GetEngineColourMap(engine_type, company, INVALID_ENGINE, NULL);
 }
 
+/**
+ * Get the colour map for a vehicle.
+ * @param v Vehicle to get colour map for
+ * @return A ready-to-use palette modifier
+ */
 PaletteID GetVehiclePalette(const Vehicle *v)
 {
 	if (v->IsGroundVehicle()) {
@@ -1823,6 +1860,11 @@ void Vehicle::LeaveStation()
 }
 
 
+/**
+ * Handle the loading of the vehicle; when not it skips through dummy
+ * orders and does nothing in all other cases.
+ * @param mode is the non-first call for this vehicle in this tick?
+ */
 void Vehicle::HandleLoading(bool mode)
 {
 	switch (this->current_order.GetType()) {
@@ -1848,6 +1890,12 @@ void Vehicle::HandleLoading(bool mode)
 	this->IncrementOrderIndex();
 }
 
+/**
+ * Send this vehicle to the depot using the given command(s).
+ * @param flags   the command flags (like execute and such).
+ * @param command the command to execute.
+ * @return the cost of the depot action.
+ */
 CommandCost Vehicle::SendToDepot(DoCommandFlag flags, DepotCommand command)
 {
 	CommandCost ret = CheckOwnership(this->owner);
@@ -1913,6 +1961,10 @@ CommandCost Vehicle::SendToDepot(DoCommandFlag flags, DepotCommand command)
 
 }
 
+/**
+ * Update the cached visual effect.
+ * @param allow_power_change true if the wagon-is-powered-state may change.
+ */
 void Vehicle::UpdateVisualEffect(bool allow_power_change)
 {
 	bool powered_before = HasBit(this->vcache.cached_vis_effect, VE_DISABLE_WAGON_POWER);
@@ -1975,6 +2027,10 @@ static const int8 _vehicle_smoke_pos[8] = {
 	1, 1, 1, 0, -1, -1, -1, 0
 };
 
+/**
+ * Draw visual effects (smoke and/or sparks) for a vehicle chain.
+ * @pre this->IsPrimaryVehicle()
+ */
 void Vehicle::ShowVisualEffect() const
 {
 	assert(this->IsPrimaryVehicle());
@@ -2092,6 +2148,10 @@ void Vehicle::ShowVisualEffect() const
 	if (sound) PlayVehicleSound(this, VSE_VISUAL_EFFECT);
 }
 
+/**
+ * Set the next vehicle of this vehicle.
+ * @param next the next vehicle. NULL removes the next vehicle.
+ */
 void Vehicle::SetNext(Vehicle *next)
 {
 	assert(this != next);
@@ -2116,6 +2176,11 @@ void Vehicle::SetNext(Vehicle *next)
 	}
 }
 
+/**
+ * Adds this vehicle to a shared vehicle chain.
+ * @param shared_chain a vehicle of the chain with shared vehicles.
+ * @pre !this->IsOrderListShared()
+ */
 void Vehicle::AddToShared(Vehicle *shared_chain)
 {
 	assert(this->previous_shared == NULL && this->next_shared == NULL);
@@ -2136,6 +2201,9 @@ void Vehicle::AddToShared(Vehicle *shared_chain)
 	shared_chain->orders.list->AddVehicle(this);
 }
 
+/**
+ * Removes the vehicle from the shared order list.
+ */
 void Vehicle::RemoveFromShared()
 {
 	/* Remember if we were first and the old window number before RemoveVehicle()
diff --git a/src/vehicle_base.h b/src/vehicle_base.h
index 5ef98313a..de592e798 100644
--- a/src/vehicle_base.h
+++ b/src/vehicle_base.h
@@ -229,10 +229,8 @@ public:
 	NewGRFCache grf_cache;              ///< Cache of often used calculated NewGRF values
 	VehicleCache vcache;                ///< Cache of often used vehicle values.
 
-	/** Create a new vehicle */
 	Vehicle(VehicleType type = VEH_INVALID);
 
-	/** Destroy all stuff that (still) needs the virtual functions to work properly */
 	void PreDestructor();
 	/** We want to 'destruct' the right class. */
 	virtual ~Vehicle();
@@ -245,11 +243,6 @@ public:
 
 	void DeleteUnreachedAutoOrders();
 
-	/**
-	 * Handle the loading of the vehicle; when not it skips through dummy
-	 * orders and does nothing in all other cases.
-	 * @param mode is the non-first call for this vehicle in this tick?
-	 */
 	void HandleLoading(bool mode = false);
 
 	/**
@@ -454,10 +447,6 @@ public:
 	 */
 	Money GetDisplayProfitLastYear() const { return (this->profit_last_year >> 8); }
 
-	/**
-	 * Set the next vehicle of this vehicle.
-	 * @param next the next vehicle. NULL removes the next vehicle.
-	 */
 	void SetNext(Vehicle *next);
 
 	/**
@@ -508,16 +497,7 @@ public:
 	 */
 	inline Order *GetFirstOrder() const { return (this->orders.list == NULL) ? NULL : this->orders.list->GetFirstOrder(); }
 
-	/**
-	 * Adds this vehicle to a shared vehicle chain.
-	 * @param shared_chain a vehicle of the chain with shared vehicles.
-	 * @pre !this->IsOrderListShared()
-	 */
 	void AddToShared(Vehicle *shared_chain);
-
-	/**
-	 * Removes the vehicle from the shared order list.
-	 */
 	void RemoveFromShared();
 
 	/**
@@ -585,29 +565,11 @@ public:
 	}
 
 
-	/**
-	 * Handle all of the aspects of a vehicle breakdown
-	 * This includes adding smoke and sounds, and ending the breakdown when appropriate.
-	 * @return true iff the vehicle is stopped because of a breakdown
-	 * @note This function always returns false for aircraft, since these never stop for breakdowns
-	 */
 	bool HandleBreakdown();
 
 	bool NeedsAutorenewing(const Company *c) const;
 
-	/**
-	 * Check if the vehicle needs to go to a depot in near future (if a opportunity presents itself) for service or replacement.
-	 *
-	 * @see NeedsAutomaticServicing()
-	 * @return true if the vehicle should go to a depot if a opportunity presents itself.
-	 */
 	bool NeedsServicing() const;
-
-	/**
-	 * Checks if the current order should be interupted for a service-in-depot-order.
-	 * @see NeedsServicing()
-	 * @return true if the current order should be interupted.
-	 */
 	bool NeedsAutomaticServicing() const;
 
 	/**
@@ -629,24 +591,9 @@ public:
 	 */
 	virtual bool FindClosestDepot(TileIndex *location, DestinationID *destination, bool *reverse) { return false; }
 
-	/**
-	 * Send this vehicle to the depot using the given command(s).
-	 * @param flags   the command flags (like execute and such).
-	 * @param command the command to execute.
-	 * @return the cost of the depot action.
-	 */
 	CommandCost SendToDepot(DoCommandFlag flags, DepotCommand command);
 
-	/**
-	 * Update the cached visual effect.
-	 * @param allow_power_change true if the wagon-is-powered-state may change.
-	 */
 	void UpdateVisualEffect(bool allow_power_change = true);
-
-	/*
-	 * Draw visual effects (smoke and/or sparks) for a vehicle chain.
-	 * @pre this->IsPrimaryVehicle()
-	 */
 	void ShowVisualEffect() const;
 
 	/**
@@ -828,16 +775,7 @@ struct FreeUnitIDGenerator {
 	UnitID maxid; ///< maximum ID at the moment of constructor call
 	UnitID curid; ///< last ID returned; 0 if none
 
-	/**
-	 * Initializes the structure. Vehicle unit numbers are supposed not to change after
-	 * struct initialization, except after each call to this->NextID() the returned value
-	 * is assigned to a vehicle.
-	 * @param type type of vehicle
-	 * @param owner owner of vehicles
-	 */
 	FreeUnitIDGenerator(VehicleType type, CompanyID owner);
-
-	/** Returns next free UnitID. Supposes the last returned value was assigned to a vehicle. */
 	UnitID NextID();
 
 	/** Releases allocated memory */
diff --git a/src/vehicle_func.h b/src/vehicle_func.h
index 930da9b47..586481513 100644
--- a/src/vehicle_func.h
+++ b/src/vehicle_func.h
@@ -105,19 +105,7 @@ static inline bool IsCompanyBuildableVehicleType(const BaseVehicle *v)
 LiveryScheme GetEngineLiveryScheme(EngineID engine_type, EngineID parent_engine_type, const Vehicle *v);
 const struct Livery *GetEngineLivery(EngineID engine_type, CompanyID company, EngineID parent_engine_type, const Vehicle *v, byte livery_setting);
 
-/**
- * Get the colour map for an engine. This used for unbuilt engines in the user interface.
- * @param engine_type ID of engine
- * @param company ID of company
- * @return A ready-to-use palette modifier
- */
 SpriteID GetEnginePalette(EngineID engine_type, CompanyID company);
-
-/**
- * Get the colour map for a vehicle.
- * @param v Vehicle to get colour map for
- * @return A ready-to-use palette modifier
- */
 SpriteID GetVehiclePalette(const Vehicle *v);
 
 uint GetVehicleCapacity(const Vehicle *v, uint16 *mail_capacity = NULL);
diff --git a/src/viewport_func.h b/src/viewport_func.h
index ff59dbb9a..9093166dd 100644
--- a/src/viewport_func.h
+++ b/src/viewport_func.h
@@ -28,11 +28,6 @@ ViewPort *IsPtInWindowViewport(const Window *w, int x, int y);
 Point GetTileBelowCursor();
 void UpdateViewportPosition(Window *w);
 
-/**
- * Mark all viewports dirty for repaint.
- *
- * @ingroup dirty
- */
 void MarkAllViewportsDirty(int left, int top, int right, int bottom);
 
 bool DoZoomInOutWindow(ZoomStateChange how, Window *w);
diff --git a/src/widget_type.h b/src/widget_type.h
index dc6f99363..4533743ed 100644
--- a/src/widget_type.h
+++ b/src/widget_type.h
@@ -338,7 +338,7 @@ public:
 	/* virtual */ void FillNestedArray(NWidgetBase **array, uint length);
 
 	/** Return whether the container is empty. */
-	inline bool IsEmpty() { return head == NULL; };
+	inline bool IsEmpty() { return head == NULL; }
 
 	/* virtual */ NWidgetBase *GetWidgetOfType(WidgetType tp);