(svn r21060) -Doc: Improved wording of comments (mostly by __ln__)

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.
  *
  * <table>

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

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);

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
+	 * Function to set up vehicle specific widgets (mainly sprites and strings).
-	 * 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
+	 * 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)
 	{

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;

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,

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 {

src/gfx.cpp

@@ -105,7 +105,7 @@ static ReusableBuffer<uint8> _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;

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;

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
  */

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
+ *         - it is not a common pattern so the implementation code is bit harder to read.
- *         - valgrind can generate warning that allocated block is lost (not accessible)
+ *         - valgrind may generate a warning that the allocated block is lost (not accessible).
  */
 class ByteBlob {
 protected:

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;
 

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 */

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. */

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.

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);

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;
 

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 */

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
+ * 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
+ * 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.

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.

src/train.h

@@ -162,7 +162,7 @@ struct Train : public GroundVehicle<Train, VEH_TRAIN> {
 		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
 	};

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.
+		 *     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.
+		 *     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.
+		 *     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.
+		 *     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.
+		 *     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.
+		 *     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.
+		 *     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.
+		 *     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

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 */

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)

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

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);

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);
 }