(svn r24584) -Doc: [Script] Improve API documentation.

src/script/api/script_engine.hpp

@@ -255,6 +255,9 @@ public:
 
 	/**
 	 * Get the maximum allowed distance between two orders for an engine.
+	 * The distance returned is a vehicle-type specific distance indepenent from other
+	 * map distances, you may use the result of this function to compare it
+	 * with the result of ScriptOrder::GetOrderDistance.
 	 * @param engine_id The engine to get the max distance for.
 	 * @pre IsValidEngine(engine_id).
 	 * @return The maximum distance between two orders for the engine

src/script/api/script_order.hpp

@@ -34,7 +34,7 @@ public:
 		/** Destination of new order is to far away from the previous order */
 		ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION,    // [STR_ERROR_TOO_FAR_FROM_PREVIOUS_DESTINATION]
 
-		/* Aircraft has not enough range to copy/share orders. */
+		/** Aircraft has not enough range to copy/share orders. */
 		ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE,                 // [STR_ERROR_AIRCRAFT_NOT_ENOUGH_RANGE]
 	};
 
@@ -585,9 +585,13 @@ public:
 
 	/**
 	 * Get the distance between two points for a vehicle type.
+	 * Use this function to compute the distance between two tiles wrt. a vehicle type.
+	 * These vehicle-type specific distances are indepenent from other map distances, you may
+	 * use the result of this function to compare it with the result of
+	 * ScriptEngine::GetMaximumOrderDistance or ScriptVehicle::GetMaximumOrderDistance.
 	 * @param vehicle_type The vehicle type to get the distance for.
 	 * @param origin_tile Origin, can be any tile or a tile of a specific station.
-	 * @param dest_tile Destination, ca be any tile or a tile of a specific station.
+	 * @param dest_tile Destination, can be any tile or a tile of a specific station.
 	 * @return The distance between the origin and the destination for a
 	 *         vehicle of the given vehicle type.
 	 * @note   The unit of the order distances is unspecified and should

src/script/api/script_tile.hpp

@@ -400,7 +400,7 @@ public:
 	/**
 	 * Level all tiles in the rectangle between start_tile and end_tile so they
 	 *  are at the same height. All tiles will be raised or lowered until
-	 *  they are at height ScriptTile::GetHeight(start_tile).
+	 *  they are at height ScriptTile::GetCornerHeight(start_tile, ScriptTile::CORNER_N).
 	 * @param start_tile One corner of the rectangle to level.
 	 * @param end_tile The opposite corner of the rectangle.
 	 * @pre start_tile < ScriptMap::GetMapSize().

src/script/api/script_vehicle.hpp

@@ -549,6 +549,9 @@ public:
 
 	/**
 	 * Get the maximum allowed distance between two orders for a vehicle.
+	 * The distance returned is a vehicle-type specific distance indepenent from other
+	 * map distances, you may use the result of this function to compare it
+	 * with the result of ScriptOrder::GetOrderDistance.
 	 * @param vehicle_id The vehicle to get the distance for.
 	 * @pre IsValidVehicle(vehicle_id).
 	 * @return The maximum distance between two orders for this vehicle