(svn r19949) -Doc: Mention tricky units (like speed) more often and more consistently.

2 files changed, 15 insertions, 15 deletions

diff --git a/src/table/bridge_land.h b/src/table/bridge_land.h
index 6fafe71a8..f5a2b7638 100644
--- a/src/table/bridge_land.h
+++ b/src/table/bridge_land.h
@@ -728,10 +728,10 @@ static const PalSpriteID * const * const _bridge_sprite_table[MAX_BRIDGES] = {
 
 /** Describes the data that defines each bridge in the game
  * @param y   year of availablity
- * @param mnl minimum length
- * @param mxl maximum length
- * @param p   price
- * @param mxs maximum speed allowed
+ * @param mnl minimum length (not counting bridge heads)
+ * @param mxl maximum length (not counting bridge heads)
+ * @param p   price multiplier
+ * @param mxs maximum speed allowed (1 unit = 1/1.6 mph = 1 km-ish/h)
  * @param spr sprite to use in purchase GUI
  * @param plt palette for the sprite in purchase GUI
  * @param dsc description of the bridge in purchase GUI
@@ -746,12 +746,12 @@ const BridgeSpec _orig_bridge[] = {
 	       year of availablity
 	       |  minimum length
 	       |  |   maximum length
-	       |  |   |    price
+	       |  |   |    price multiplier
 	       |  |   |    |    maximum speed
 	       |  |   |    |    |  sprite to use in GUI
 	       |  |   |    |    |  |      palette in GUI
-	   string with description               name on rail                                     name on road
-	   |                              |      |                                                | */
+	   string with description               name on rail                                         name on road
+	   |                              |      |                                                    | */
 	MBR(   0, 0, 16,  80,  32, 0xA24, PAL_NONE,
 	   STR_BRIDGE_NAME_WOODEN,               STR_LAI_BRIDGE_DESCRIPTION_RAIL_WOODEN,              STR_LAI_BRIDGE_DESCRIPTION_ROAD_WOODEN),
 
diff --git a/src/table/engines.h b/src/table/engines.h
index 4131fd880..f92e3e04b 100644
--- a/src/table/engines.h
+++ b/src/table/engines.h
@@ -19,7 +19,7 @@
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
- * @param d base life
+ * @param d base life (years)
  * @param e cargo type
  * @param f Bitmask of the climates
  * @note the 0x80 in parameter b sets the "is carriage bit"
@@ -31,7 +31,7 @@
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
- * @param d base life
+ * @param d base life (years)
  * @param e cargo type
  * @param f Bitmask of the climates
  * @see MK
@@ -43,7 +43,7 @@
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
- * @param d base life
+ * @param d base life (years)
  * @param e cargo type
  * @param f Bitmask of the climates
  * @see MK
@@ -55,7 +55,7 @@
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
- * @param d base life
+ * @param d base life (years)
  * @param e Bitmask of the climates
  * @see MK
  * @note the 20 between b and e is the load amount
@@ -347,7 +347,7 @@ static const EngineInfo _orig_engine_info[] = {
  * @param a image_index
  * @param b type
  * @param c cost_factor
- * @param d max_speed
+ * @param d max_speed (1 unit = 1/1.6 mph = 1 km-ish/h)
  * @param e power (hp)
  * @param f weight (tons)
  * @param g running_cost
@@ -527,7 +527,7 @@ static const RailVehicleInfo _orig_rail_vehicle_info[] = {
  * @see ShipVehicleInfo
  * @param a image_index
  * @param b cost_factor
- * @param c max_speed
+ * @param c max_speed (1 unit = 1/3.2 mph = 0.5 km-ish/h)
  * @param d capacity (persons, bags, tons, pieces, items, cubic metres, ...)
  * @param e running_cost
  * @param f sound effect
@@ -561,7 +561,7 @@ static const ShipVehicleInfo _orig_ship_vehicle_info[] = {
  * @param d subtype (bit 0 - plane, bit 1 - large plane)
  * @param e sound effect
  * @param f acceleration
- * @param g max_speed
+ * @param g max_speed (1 unit = 8 mph = 12.8 km-ish/h)
  * @param h mail_capacity (bags)
  * @param i passenger_capacity (persons)
  */
@@ -628,7 +628,7 @@ static const AircraftVehicleInfo _orig_aircraft_vehicle_info[] = {
  * @param b cost_factor
  * @param c running_cost
  * @param d sound effect
- * @param e max_speed
+ * @param e max_speed (1 unit = 1/3.2 mph = 0.5 km-ish/h)
  * @param f capacity (persons, bags, tons, pieces, items, cubic metres, ...)
  * @param g weight (1/4 ton)
  * @param h power (10 hp)