From 7e48d85104549cbb3604aa7eb262b922dbc3f640 Mon Sep 17 00:00:00 2001 From: alberth Date: Sat, 30 Oct 2010 17:51:07 +0000 Subject: [PATCH] (svn r21060) -Doc: Improved wording of comments (mostly by __ln__) --- src/ai/api/ai_types.hpp | 2 +- src/autoreplace_cmd.cpp | 2 +- src/build_vehicle_gui.cpp | 2 +- src/depot_gui.cpp | 10 ++++++---- src/economy_type.h | 4 ++-- src/elrail.cpp | 2 +- src/fileio.cpp | 2 +- src/gfx.cpp | 2 +- src/industry_gui.cpp | 2 +- src/landscape.cpp | 2 +- src/misc/blob.hpp | 6 +++--- src/newgrf_house.cpp | 2 +- src/pathfinder/yapf/nodelist.hpp | 2 +- src/rail_cmd.cpp | 4 ++-- src/slope_func.h | 2 +- src/station_cmd.cpp | 4 ++-- src/table/sprites.h | 2 +- src/terraform_cmd.cpp | 2 +- src/tgp.cpp | 4 ++-- src/track_func.h | 2 +- src/train.h | 2 +- src/train_cmd.cpp | 16 ++++++++-------- src/tunnelbridge_cmd.cpp | 4 ++-- src/vehicle.cpp | 2 +- src/vehicle_cmd.cpp | 2 +- src/viewport.cpp | 2 +- src/window.cpp | 2 +- 27 files changed, 46 insertions(+), 44 deletions(-) diff --git a/src/ai/api/ai_types.hpp b/src/ai/api/ai_types.hpp index 7308a0452b..e1f76bcc06 100644 --- a/src/ai/api/ai_types.hpp +++ b/src/ai/api/ai_types.hpp @@ -12,7 +12,7 @@ * * IDs are used to identify certain objects. They are only unique within the object type, so for example a vehicle may have VehicleID 2009, * while a station has StationID 2009 at the same time. Also IDs are assigned arbitrary, you cannot assume them to be consecutive. - * Also note, that some IDs are static and never change, while others are allocated dynamically and might be + * Also note that some IDs are static and never change, while others are allocated dynamically and might be * reused for other objects once they are released. So be careful, which IDs you store for which purpose and whether they stay valid all the time. * * diff --git a/src/autoreplace_cmd.cpp b/src/autoreplace_cmd.cpp index 17860e8bf8..1ba2d8f0a9 100644 --- a/src/autoreplace_cmd.cpp +++ b/src/autoreplace_cmd.cpp @@ -155,7 +155,7 @@ static bool VerifyAutoreplaceRefitForOrders(const Vehicle *v, EngineID engine_ty /** * Function to find what type of cargo to refit to when autoreplacing - * @param *v Original vehicle, that is being replaced + * @param *v Original vehicle that is being replaced. * @param engine_type The EngineID of the vehicle that is being replaced to * @param part_of_chain The vehicle is part of a train * @return The cargo type to replace to diff --git a/src/build_vehicle_gui.cpp b/src/build_vehicle_gui.cpp index 7c953a5ab8..d5bbdf4603 100644 --- a/src/build_vehicle_gui.cpp +++ b/src/build_vehicle_gui.cpp @@ -689,7 +689,7 @@ int DrawVehiclePurchaseInfo(int left, int right, int y, EngineID engine_number) } } - /* Draw details, that applies to all types except rail wagons */ + /* Draw details that apply to all types except rail wagons. */ if (e->type != VEH_TRAIN || e->u.rail.railveh_type != RAILVEH_WAGON) { /* Design date - Life length */ SetDParam(0, ymd.year); diff --git a/src/depot_gui.cpp b/src/depot_gui.cpp index 6f9a04bd7d..05ef295e62 100644 --- a/src/depot_gui.cpp +++ b/src/depot_gui.cpp @@ -356,7 +356,7 @@ struct DepotWindow : Window { maxval = min(this->vehicle_list.Length() + this->wagon_list.Length(), (this->vscroll->GetPosition() * boxes_in_each_row) + (rows_in_display * boxes_in_each_row)); - /* draw the train wagons, that do not have an engine in front */ + /* Draw the train wagons without an engine in front. */ for (; num < maxval; num++, y += this->resize.step_height) { const Vehicle *v = this->wagon_list[num - this->vehicle_list.Length()]; this->DrawVehicleInDepot(v, r.left, r.right, y); @@ -537,9 +537,11 @@ struct DepotWindow : Window { } } - /* Function to set up vehicle specific widgets (mainly sprites and strings). - * Only use this if it's the same widget, that's used for more than one vehicle type and it needs different text/sprites - * Vehicle specific text/sprites, that's in a widget, that's only shown for one vehicle type (like sell whole train) is set in the nested widget array + /** + * Function to set up vehicle specific widgets (mainly sprites and strings). + * Only use this function to if the widget is used for several vehicle types and each has + * different text/sprites. If the widget is only used for a single vehicle type, or the same + * text/sprites are used every time, use the nested widget array to initialize the widget. */ void SetupWidgetData(VehicleType type) { diff --git a/src/economy_type.h b/src/economy_type.h index 1b79ade5c3..d648c9b09d 100644 --- a/src/economy_type.h +++ b/src/economy_type.h @@ -175,7 +175,7 @@ enum PriceCategory { struct PriceBaseSpec { Money start_price; ///< Default value at game start, before adding multipliers. PriceCategory category; ///< Price is affected by certain difficulty settings. - uint grf_feature; ///< GRF Feature, that decides whether price multipliers apply locally or globally. GSF_END if none. + uint grf_feature; ///< GRF Feature that decides whether price multipliers apply locally or globally, #GSF_END if none. Price fallback_price; ///< Fallback price multiplier for new prices but old grfs. }; @@ -187,7 +187,7 @@ static const int LOAN_INTERVAL = 10000; * This allows for 32 bit base prices (21 are currently needed). * Considering the sign bit and 16 fractional bits, there are 15 bits left. * 170 years of 4% inflation result in a inflation of about 822, so 10 bits are actually enough. - * Note, that NewGRF multipliers share the 16 fractional bits. + * Note that NewGRF multipliers share the 16 fractional bits. * @see MAX_PRICE_MODIFIER */ static const uint64 MAX_INFLATION = (1ull << (63 - 32)) - 1; diff --git a/src/elrail.cpp b/src/elrail.cpp index 5457ca0b23..7bc8f98b0e 100644 --- a/src/elrail.cpp +++ b/src/elrail.cpp @@ -465,7 +465,7 @@ static void DrawCatenaryRailway(const TileInfo *ti) /* * The "wire"-sprite position is inside the tile, i.e. 0 <= sss->?_offset < TILE_SIZE. * Therefore it is safe to use GetSlopeZ() for the elevation. - * Also note, that the result of GetSlopeZ() is very special for bridge-ramps. + * Also note that the result of GetSlopeZ() is very special for bridge-ramps. */ AddSortableSpriteToDraw(wire_base + sss->image_offset, PAL_NONE, ti->x + sss->x_offset, ti->y + sss->y_offset, sss->x_size, sss->y_size, sss->z_size, GetSlopeZ(ti->x + sss->x_offset, ti->y + sss->y_offset) + sss->z_offset, diff --git a/src/fileio.cpp b/src/fileio.cpp index b10c544596..c90d28f9ff 100644 --- a/src/fileio.cpp +++ b/src/fileio.cpp @@ -704,7 +704,7 @@ bool TarScanner::AddFile(const char *filename, size_t basepath_length) } /* Truncate 'dest' after last PATHSEPCHAR. - * This assumes, that the truncated part is a real directory and not a link */ + * This assumes that the truncated part is a real directory and not a link. */ destpos = strrchr(dest, PATHSEPCHAR); if (destpos == NULL) destpos = dest; } else { diff --git a/src/gfx.cpp b/src/gfx.cpp index 78fd33278d..e28255db26 100644 --- a/src/gfx.cpp +++ b/src/gfx.cpp @@ -105,7 +105,7 @@ static ReusableBuffer _cursor_backup; */ static Rect _invalid_rect; static const byte *_colour_remap_ptr; -static byte _string_colourremap[3]; ///< Recoloursprite for stringdrawing. The grf loader ensures, that ST_FONT sprites only use colours 0 to 2. +static byte _string_colourremap[3]; ///< Recoloursprite for stringdrawing. The grf loader ensures that #ST_FONT sprites only use colours 0 to 2. static const uint DIRTY_BLOCK_HEIGHT = 8; static const uint DIRTY_BLOCK_WIDTH = 64; diff --git a/src/industry_gui.cpp b/src/industry_gui.cpp index 4e56b4055a..0766122c8a 100644 --- a/src/industry_gui.cpp +++ b/src/industry_gui.cpp @@ -2019,7 +2019,7 @@ next_cargo: ; * * When displaying the cargoes around an industry type, five columns are needed (supplying industries, accepted cargoes, the industry, * produced cargoes, customer industries). Displaying the industries around a cargo needs three columns (supplying industries, the cargo, - * customer industries). The remaining two columns are set to #CFT_EMPTY, that has a width equal to the average of a cargo and an industry column. + * customer industries). The remaining two columns are set to #CFT_EMPTY with a width equal to the average of a cargo and an industry column. */ struct IndustryCargoesWindow : public Window { static const int HOR_TEXT_PADDING, VERT_TEXT_PADDING; diff --git a/src/landscape.cpp b/src/landscape.cpp index 6f34a17880..db54810b23 100644 --- a/src/landscape.cpp +++ b/src/landscape.cpp @@ -78,7 +78,7 @@ extern const byte _slope_to_sprite_offset[32] = { * Description of the snow line throughout the year. * * If it is \c NULL, a static snowline height is used, as set by \c _settings_game.game_creation.snow_line. - * Otherwise it points to a table loaded from a newGRF file, that describes the variable snowline + * Otherwise it points to a table loaded from a newGRF file that describes the variable snowline. * @ingroup SnowLineGroup * @see GetSnowLine() GameCreationSettings */ diff --git a/src/misc/blob.hpp b/src/misc/blob.hpp index ff9cebd67b..c3ae103d61 100644 --- a/src/misc/blob.hpp +++ b/src/misc/blob.hpp @@ -41,10 +41,10 @@ * which is good for performance (assuming that data are accessed most often). * - sizeof(blob) is the same as the size of any other pointer * 6. Drawbacks of this layout: - * - the fact, that pointer to the alocated block is adjusted by sizeof(BlobHeader) before + * - the fact that a pointer to the allocated block is adjusted by sizeof(BlobHeader) before * it is stored can lead to several confusions: - * - it is not common pattern so the implementation code is bit harder to read - * - valgrind can generate warning that allocated block is lost (not accessible) + * - it is not a common pattern so the implementation code is bit harder to read. + * - valgrind may generate a warning that the allocated block is lost (not accessible). */ class ByteBlob { protected: diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp index d9362121b9..137f0adf25 100644 --- a/src/newgrf_house.cpp +++ b/src/newgrf_house.cpp @@ -138,7 +138,7 @@ uint32 GetNearbyTileInformation(byte parameter, TileIndex tile) /** Structure with user-data for SearchNearbyHouseXXX - functions */ typedef struct { - const HouseSpec *hs; ///< Specs of the house, that started the search + const HouseSpec *hs; ///< Specs of the house that started the search. TileIndex north_tile; ///< Northern tile of the house. } SearchNearbyHouseData; diff --git a/src/pathfinder/yapf/nodelist.hpp b/src/pathfinder/yapf/nodelist.hpp index 5a92e4ae70..a6e5c2b501 100644 --- a/src/pathfinder/yapf/nodelist.hpp +++ b/src/pathfinder/yapf/nodelist.hpp @@ -80,7 +80,7 @@ public: return m_new_node; } - /** notify the nodelist, that we don't want to discard the given node */ + /** Notify the nodelist that we don't want to discard the given node. */ FORCEINLINE void FoundBestNode(Titem_& item) { /* for now it is enough to invalidate m_new_node if it is our given node */ diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp index 59f52c524e..11633e0616 100644 --- a/src/rail_cmd.cpp +++ b/src/rail_cmd.cpp @@ -1634,7 +1634,7 @@ static CommandCost ClearTile_Track(TileIndex tile, DoCommandFlag flags) case RAIL_TILE_SIGNALS: case RAIL_TILE_NORMAL: { Slope tileh = GetTileSlope(tile, NULL); - /* Is there flat water on the lower halftile, that gets cleared expensively? */ + /* Is there flat water on the lower halftile that gets cleared expensively? */ bool water_ground = (GetRailGroundType(tile) == RAIL_GROUND_WATER && IsSlopeWithOneCornerRaised(tileh)); TrackBits tracks = GetTrackBits(tile); @@ -2830,7 +2830,7 @@ static CommandCost TerraformTile_Track(TileIndex tile, DoCommandFlag flags, uint Slope tileh_old = GetTileSlope(tile, &z_old); if (IsPlainRail(tile)) { TrackBits rail_bits = GetTrackBits(tile); - /* Is there flat water on the lower halftile, that must be cleared expensively? */ + /* Is there flat water on the lower halftile that must be cleared expensively? */ bool was_water = (GetRailGroundType(tile) == RAIL_GROUND_WATER && IsSlopeWithOneCornerRaised(tileh_old)); /* First test autoslope. However if it succeeds we still have to test the rest, because non-autoslope terraforming is cheaper. */ diff --git a/src/slope_func.h b/src/slope_func.h index c05df56567..f151b4cd76 100644 --- a/src/slope_func.h +++ b/src/slope_func.h @@ -239,7 +239,7 @@ static inline DiagDirection GetInclinedSlopeDirection(Slope s) } /** - * Returns the slope, that is inclined in a specific direction. + * Returns the slope that is inclined in a specific direction. * * @param dir A #DiagDirection * @return The #Slope that goes up in direction dir. diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp index 8d299f1f1f..cee335fc12 100644 --- a/src/station_cmd.cpp +++ b/src/station_cmd.cpp @@ -2139,7 +2139,7 @@ CommandCost CmdBuildAirport(TileIndex tile, DoCommandFlag flags, uint32 p1, uint CommandCost cost = CheckFlatLand(TileArea(tile, w, h), flags); if (cost.Failed()) return cost; - /* Go get the final noise level, that is base noise minus factor from distance to town center */ + /* The noise level is the noise from the airport and reduce it to account for the distance to the town center. */ Town *nearest = AirportGetNearestTown(as, tile); uint newnoise_level = GetAirportNoiseLevelForTown(as, nearest->xy, tile); @@ -2304,7 +2304,7 @@ static CommandCost RemoveAirport(TileIndex tile, DoCommandFlag flags) ); } - /* Go get the final noise level, that is base noise minus factor from distance to town center. + /* The noise level is the noise from the airport and reduce it to account for the distance to the town center. * And as for construction, always remove it, even if the setting is not set, in order to avoid the * need of recalculation */ Town *nearest = AirportGetNearestTown(as, tile); diff --git a/src/table/sprites.h b/src/table/sprites.h index 5e84181805..bb4a0774f5 100644 --- a/src/table/sprites.h +++ b/src/table/sprites.h @@ -268,7 +268,7 @@ static const uint16 ONEWAY_SPRITE_COUNT = 6; static const SpriteID SPR_FLAGS_BASE = SPR_ONEWAY_BASE + ONEWAY_SPRITE_COUNT; static const uint16 FLAGS_SPRITE_COUNT = 36; -/* Not really a sprite, but an empty bounding box. Used to construct bounding boxes, that help sorting the sprites, but do not have a sprite associated. */ +/* Not really a sprite, but an empty bounding box. Used to construct bounding boxes that help sorting the sprites, but do not have a sprite associated. */ static const SpriteID SPR_EMPTY_BOUNDING_BOX = SPR_FLAGS_BASE + FLAGS_SPRITE_COUNT; static const uint16 EMPTY_BOUNDING_BOX_SPRITE_COUNT = 1; diff --git a/src/terraform_cmd.cpp b/src/terraform_cmd.cpp index 72387fac16..9582ff186e 100644 --- a/src/terraform_cmd.cpp +++ b/src/terraform_cmd.cpp @@ -178,7 +178,7 @@ static CommandCost TerraformTileHeight(TerraformerState *ts, TileIndex tile, int return_cmd_error(STR_ERROR_TOO_CLOSE_TO_EDGE_OF_MAP); } - /* Mark incident tiles, that are involved in the terraforming */ + /* Mark incident tiles that are involved in the terraforming. */ TerraformAddDirtyTileAround(ts, tile); /* Store the height modification */ diff --git a/src/tgp.cpp b/src/tgp.cpp index f936175fb1..239cb17286 100644 --- a/src/tgp.cpp +++ b/src/tgp.cpp @@ -22,8 +22,8 @@ * * Quickie guide to Perlin Noise * Perlin noise is a predictable pseudo random number sequence. By generating - * it in 2 dimensions, it becomes a useful random map, that for a given seed - * and starting X & Y is entirely predictable. On the face of it, that may not + * it in 2 dimensions, it becomes a useful random map that, for a given seed + * and starting X & Y, is entirely predictable. On the face of it, that may not * be useful. However, it means that if you want to replay a map in a different * terrain, or just vary the sea level, you just re-run the generator with the * same seed. The seed is an int32, and is randomised on each run of New Game. diff --git a/src/track_func.h b/src/track_func.h index 853863f584..a497dd4993 100644 --- a/src/track_func.h +++ b/src/track_func.h @@ -62,7 +62,7 @@ static inline TrackBits AxisToTrackBits(Axis a) } /** - * Returns a single horizontal/vertical trackbit, that is in a specific tile corner. + * Returns a single horizontal/vertical trackbit that is in a specific tile corner. * * @param corner The corner of a tile. * @return The TrackBits of the track in the corner. diff --git a/src/train.h b/src/train.h index 2f51871c9c..8b2d619ac2 100644 --- a/src/train.h +++ b/src/train.h @@ -162,7 +162,7 @@ struct Train : public GroundVehicle { TS_FRONT = 0, ///< Leading engine of a train TS_ARTICULATED_PART = 1, ///< Articulated part of an engine TS_WAGON = 2, ///< Wagon - TS_ENGINE = 3, ///< Engine, that can be front engine, but might be placed behind another engine + TS_ENGINE = 3, ///< Engine that can be front engine, but might be placed behind another engine. TS_FREE_WAGON = 4, ///< First in a wagon chain (in depot) TS_MULTIHEADED = 5, ///< Engine is multiheaded }; diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp index a34cf77c92..5a80a9880f 100644 --- a/src/train_cmd.cpp +++ b/src/train_cmd.cpp @@ -1247,19 +1247,19 @@ CommandCost CmdMoveRailVehicle(TileIndex tile, DoCommandFlag flags, uint32 p1, u /* There are 14 different cases: * 1) front engine gets moved to a new train, it stays a front engine. - * a) the 'next' part is a wagon, that becomes a free wagon chain. - * b) the 'next' part is an engine, that becomes a front engine. + * a) the 'next' part is a wagon that becomes a free wagon chain. + * b) the 'next' part is an engine that becomes a front engine. * c) there is no 'next' part, nothing else happens * 2) front engine gets moved to another train, it is not a front engine anymore - * a) the 'next' part is a wagon, that becomes a free wagon chain. - * b) the 'next' part is an engine, that becomes a front engine. + * a) the 'next' part is a wagon that becomes a free wagon chain. + * b) the 'next' part is an engine that becomes a front engine. * c) there is no 'next' part, nothing else happens * 3) front engine gets moved to later in the current train, it is not an engine anymore. - * a) the 'next' part is a wagon, that becomes a free wagon chain. - * b) the 'next' part is an engine, that becomes a front engine. + * a) the 'next' part is a wagon that becomes a free wagon chain. + * b) the 'next' part is an engine that becomes a front engine. * 4) free wagon gets moved - * a) the 'next' part is a wagon, that becomes a free wagon chain. - * b) the 'next' part is an engine, that becomes a front engine. + * a) the 'next' part is a wagon that becomes a free wagon chain. + * b) the 'next' part is an engine that becomes a front engine. * c) there is no 'next' part, nothing else happens * 5) non front engine gets moved and becomes a new train, nothing else happens * 6) non front engine gets moved within a train / to another train, nothing hapens diff --git a/src/tunnelbridge_cmd.cpp b/src/tunnelbridge_cmd.cpp index 2f5ec5dfa8..37cd75cb2b 100644 --- a/src/tunnelbridge_cmd.cpp +++ b/src/tunnelbridge_cmd.cpp @@ -1060,7 +1060,7 @@ static void DrawTile_TunnelBridge(TileInfo *ti) if (catenary) EndSpriteCombine(); - /* Add helper BB for sprite sorting, that separate the tunnel from things beside of it */ + /* Add helper BB for sprite sorting that separates the tunnel from things beside of it. */ AddSortableSpriteToDraw(SPR_EMPTY_BOUNDING_BOX, PAL_NONE, ti->x, ti->y, BB_data[6], BB_data[7], TILE_HEIGHT, ti->z); AddSortableSpriteToDraw(SPR_EMPTY_BOUNDING_BOX, PAL_NONE, ti->x + BB_data[4], ti->y + BB_data[5], BB_data[6], BB_data[7], TILE_HEIGHT, ti->z); @@ -1249,7 +1249,7 @@ void DrawBridgeMiddle(const TileInfo *ti) uint bridge_z = GetBridgeHeight(rampsouth); uint z = bridge_z - BRIDGE_Z_START; - /* Add a bounding box, that separates the bridge from things below it. */ + /* Add a bounding box that separates the bridge from things below it. */ AddSortableSpriteToDraw(SPR_EMPTY_BOUNDING_BOX, PAL_NONE, x, y, 16, 16, 1, bridge_z - TILE_HEIGHT + BB_Z_SEPARATOR); /* Draw Trambits as SpriteCombine */ diff --git a/src/vehicle.cpp b/src/vehicle.cpp index 5cb07b6c6f..dc155f9ac5 100644 --- a/src/vehicle.cpp +++ b/src/vehicle.cpp @@ -706,7 +706,7 @@ Vehicle::~Vehicle() } /** - * Adds a vehicle to the list of vehicles, that visited a depot this tick + * Adds a vehicle to the list of vehicles that visited a depot this tick * @param *v vehicle to add */ void VehicleEnteredDepotThisTick(Vehicle *v) diff --git a/src/vehicle_cmd.cpp b/src/vehicle_cmd.cpp index b3a7d5ec26..84f9609768 100644 --- a/src/vehicle_cmd.cpp +++ b/src/vehicle_cmd.cpp @@ -636,7 +636,7 @@ CommandCost CmdCloneVehicle(TileIndex tile, DoCommandFlag flags, uint32 p1, uint /* * v_front is the front engine in the original vehicle - * v is the car/vehicle of the original vehicle, that is currently being copied + * v is the car/vehicle of the original vehicle that is currently being copied * w_front is the front engine of the cloned vehicle * w is the car/vehicle currently being cloned * w_rear is the rear end of the cloned train. It's used to add more cars and is only used by trains diff --git a/src/viewport.cpp b/src/viewport.cpp index c41c2d3094..3b25c9efea 100644 --- a/src/viewport.cpp +++ b/src/viewport.cpp @@ -821,7 +821,7 @@ static void AddStringToDraw(int x, int y, StringID string, uint64 params_1, uint */ static void DrawSelectionSprite(SpriteID image, PaletteID pal, const TileInfo *ti, int z_offset, FoundationPart foundation_part) { - /* FIXME: This is not totally valid for some autorail highlights, that extent over the edges of the tile. */ + /* FIXME: This is not totally valid for some autorail highlights that extend over the edges of the tile. */ if (_vd.foundation[foundation_part] == -1) { /* draw on real ground */ AddTileSpriteToDraw(image, pal, ti->x, ti->y, ti->z + z_offset); diff --git a/src/window.cpp b/src/window.cpp index 08ed1adb16..9d82132616 100644 --- a/src/window.cpp +++ b/src/window.cpp @@ -764,7 +764,7 @@ restart_search: } } - /* Also delete the company specific windows, that don't have a company-colour */ + /* Also delete the company specific windows that don't have a company-colour. */ DeleteWindowById(WC_BUY_COMPANY, id); }