From 3dd1cf60498bd684271699917abc0deee171e66f Mon Sep 17 00:00:00 2001 From: rubidium Date: Tue, 18 Jan 2011 21:58:22 +0000 Subject: [PATCH] (svn r21843) -Codechange: move documentation towards the code to make it more likely to be updates [t-z]. --- src/tilearea.cpp | 8 ++++++ src/tilearea_type.h | 8 ------ src/vehicle.cpp | 68 +++++++++++++++++++++++++++++++++++++++++++++ src/vehicle_base.h | 62 ----------------------------------------- src/vehicle_func.h | 12 -------- src/viewport_func.h | 5 ---- src/widget_type.h | 2 +- 7 files changed, 77 insertions(+), 88 deletions(-) diff --git a/src/tilearea.cpp b/src/tilearea.cpp index 498714ec05..7a5bf9f44c 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 23813eeb8e..219416acf7 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 04521043c5..397c13a99a 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 5ef98313ad..de592e7981 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 930da9b479..5864815138 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 ff59dbb9a2..9093166dd7 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 dc6f993635..4533743edb 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);