--- a/src/ai/api/ai_tunnel.hpp	Sun Jun 15 23:35:40 2008 +0000
+++ b/src/ai/api/ai_tunnel.hpp	Mon Jun 16 00:07:49 2008 +0000
@@ -58,6 +58,9 @@
 	 * Builds a tunnel starting at start. The direction of the tunnel depends
 	 *  on the slope of the start tile. Tunnels can be created for either
 	 *  rails or roads; use the appropriate AIVehicle::VehicleType.
+	 * As an extra for road, this functions builds two half-pieces of road on
+	 *  each end of the tunnel, making it easier for you to connect it to your
+	 *  network.
 	 * @param start Where to start the tunnel.
 	 * @param vehicle_type The vehicle-type of tunnel to build.
 	 * @pre AIMap::IsValidTile(start).
@@ -69,6 +72,8 @@
 	 * @exception AITunnel::ERR_TUNNEL_END_SITE_UNSUITABLE
 	 * @return Whether the tunnel has been/can be build or not.
 	 * @note The slope of a tile can be determined by AITile::GetSlope(TileIndex).
+	 * @note No matter if the road pieces were build or not, if building the
+	 *  tunnel succeeded, this function returns true.
 	 */
 	static bool BuildTunnel(AIVehicle::VehicleType vehicle_type, TileIndex start);