From eea2f90da74546d7587f51c4080e6380aecbaa98 Mon Sep 17 00:00:00 2001 From: alberth Date: Sat, 29 Jan 2011 21:37:11 +0000 Subject: [PATCH] (svn r21925) -Doc: Doxygen additions and markup corrections to vehicle-related functions. --- src/roadveh_cmd.cpp | 10 ++++++++++ src/train.h | 26 ++++++++------------------ src/vehicle.cpp | 25 ++++++++++++++++++++++--- src/vehicle_base.h | 4 ++-- 4 files changed, 42 insertions(+), 23 deletions(-) diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp index d13c94b918..931c74d1cd 100644 --- a/src/roadveh_cmd.cpp +++ b/src/roadveh_cmd.cpp @@ -155,6 +155,11 @@ void DrawRoadVehEngine(int left, int right, int preferred_x, int y, EngineID eng DrawSprite(sprite, pal, preferred_x, y); } +/** + * Get length of a road vehicle. + * @param v Road vehicle to query length. + * @return Length of the given road vehicle. + */ static uint GetRoadVehLength(const RoadVehicle *v) { uint length = 8; @@ -167,6 +172,11 @@ static uint GetRoadVehLength(const RoadVehicle *v) return length; } +/** + * Update the cache of a road vehicle. + * @param v Road vehicle needing an update of its cache. + * @pre \a v must be first road vehicle. + */ void RoadVehUpdateCache(RoadVehicle *v) { assert(v->type == VEH_ROAD); diff --git a/src/train.h b/src/train.h index e416dd3d9c..94848bf52c 100644 --- a/src/train.h +++ b/src/train.h @@ -21,26 +21,16 @@ struct Train; +/** Rail vehicle flags. */ enum VehicleRailFlags { - VRF_REVERSING = 0, + VRF_REVERSING = 0, + VRF_POWEREDWAGON = 3, ///< Wagon is powered. + VRF_REVERSE_DIRECTION = 4, ///< Reverse the visible direction of the vehicle. - /* used to store if a wagon is powered or not */ - VRF_POWEREDWAGON = 3, - - /* used to reverse the visible direction of the vehicle */ - VRF_REVERSE_DIRECTION = 4, - - /* used to mark that electric train engine is allowed to run on normal rail */ - VRF_EL_ENGINE_ALLOWED_NORMAL_RAIL = 6, - - /* used for vehicle var 0xFE bit 8 (toggled each time the train is reversed, accurate for first vehicle only) */ - VRF_TOGGLE_REVERSE = 7, - - /* used to mark a train that can't get a path reservation */ - VRF_TRAIN_STUCK = 8, - - /* used to mark a train that is just leaving a station */ - VRF_LEAVING_STATION = 9, + VRF_EL_ENGINE_ALLOWED_NORMAL_RAIL = 6, ///< Electric train engine is allowed to run on normal rail. */ + VRF_TOGGLE_REVERSE = 7, ///< Used for vehicle var 0xFE bit 8 (toggled each time the train is reversed, accurate for first vehicle only). + VRF_TRAIN_STUCK = 8, ///< Train can't get a path reservation. + VRF_LEAVING_STATION = 9, ///< Train is just leaving a station. }; /** Modes for ignoring signals. */ diff --git a/src/vehicle.cpp b/src/vehicle.cpp index fe5cf1842c..d2e4556d48 100644 --- a/src/vehicle.cpp +++ b/src/vehicle.cpp @@ -903,6 +903,10 @@ static void DoDrawVehicle(const Vehicle *v) v->x_extent, v->y_extent, v->z_extent, v->z_pos, (v->vehstatus & VS_SHADOW) != 0); } +/** + * Add the vehicle sprites that should be drawn at a part of the screen. + * @param dpi Rectangle being drawn. + */ void ViewportAddVehicles(DrawPixelInfo *dpi) { /* The bounding rectangle */ @@ -954,6 +958,13 @@ void ViewportAddVehicles(DrawPixelInfo *dpi) } } +/** + * Find the vehicle close to the clicked coordinates. + * @param vp Viewport clicked in. + * @param x X coordinate in the viewport. + * @param y Y coordinate in the viewport. + * @return Closest vehicle, or \c NULL if none found. + */ Vehicle *CheckClickOnVehicle(const ViewPort *vp, int x, int y) { Vehicle *found = NULL, *v; @@ -984,6 +995,10 @@ Vehicle *CheckClickOnVehicle(const ViewPort *vp, int x, int y) return found; } +/** + * Decrease the value of a vehicle. + * @param v %Vehicle to devaluate. + */ void DecreaseVehicleValue(Vehicle *v) { v->value -= v->value >> 8; @@ -1187,6 +1202,10 @@ uint8 CalcPercentVehicleFilled(const Vehicle *v, StringID *colour) return (count * 100) / max; } +/** + * Vehicle entirely entered the depot, update its status, orders, vehicle windows, service it, etc. + * @param v Vehicle that entered a depot. + */ void VehicleEnterDepot(Vehicle *v) { /* Always work with the front of the vehicle */ @@ -2357,11 +2376,11 @@ const GroundVehicleCache *Vehicle::GetGroundVehicleCache() const /** * Calculates the set of vehicles that will be affected by a given selection. - * @param set Set of affected vehicles. + * @param set [inout] Set of affected vehicles. * @param v First vehicle of the selection. * @param num_vehicles Number of vehicles in the selection (not counting articulated parts). - * @pre \c set must be empty. - * @post \c set will contain the vehicles that will be refitted. + * @pre \a set must be empty. + * @post \a set will contain the vehicles that will be refitted. */ void GetVehicleSet(VehicleSet &set, Vehicle *v, uint8 num_vehicles) { diff --git a/src/vehicle_base.h b/src/vehicle_base.h index 60de8b968f..c12232ec00 100644 --- a/src/vehicle_base.h +++ b/src/vehicle_base.h @@ -118,7 +118,7 @@ extern bool LoadOldVehicle(LoadgameState *ls, int num); extern bool AfterLoadGame(); extern void FixOldVehicles(); -/** Vehicle data structure. */ +/** %Vehicle data structure. */ struct Vehicle : VehiclePool::PoolItem<&_vehicle_pool>, BaseVehicle { private: Vehicle *next; ///< pointer to the next vehicle in the chain @@ -141,7 +141,7 @@ public: /** * Heading for this tile. * For airports and train stations this tile does not necessarily belong to the destination station, - * but it can be used for heuristical purposes to estimate the distance. + * but it can be used for heuristic purposes to estimate the distance. */ TileIndex dest_tile;