Doc: [Script] Add a note about how wagon connectivity works for scripts

bin/ai/regression/tst_regression/main.nut

@@ -1690,6 +1690,9 @@ function Regression::Vehicle()
 	print("  BuildVehicle():       " + AIVehicle.BuildVehicle(10008, 9));
 	print("  BuildVehicle():       " + AIVehicle.BuildVehicle(10008, 27));
 	print("  BuildVehicle():       " + AIVehicle.BuildVehicle(10008, 27));
+	print("  IsValidVehicle(17):   " + AIVehicle.IsValidVehicle(17));
+	print("  IsValidVehicle(18):   " + AIVehicle.IsValidVehicle(18));
+	print("  IsValidVehicle(19):   " + AIVehicle.IsValidVehicle(19)); // 19 is immediately joined to 18
 	print("  MoveWagonChain():     " + AIVehicle.MoveWagonChain(18, 0, 17, 0));
 	print("  GetNumWagons():       " + AIVehicle.GetNumWagons(17));
 	print("  GetLength():          " + AIVehicle.GetLength(17));

bin/ai/regression/tst_regression/result.txt

@@ -9115,6 +9115,9 @@ ERROR: IsEnd() is invalid as Begin() is never called
   BuildVehicle():       17
   BuildVehicle():       18
   BuildVehicle():       19
+  IsValidVehicle(17):   true
+  IsValidVehicle(18):   true
+  IsValidVehicle(19):   false
   MoveWagonChain():     true
   GetNumWagons():       3
   GetLength():          24

src/script/api/script_vehicle.hpp

@@ -312,6 +312,10 @@ public:
 	 * @return The VehicleID of the new vehicle, or an invalid VehicleID when
 	 *   it failed. Check the return value using IsValidVehicle. In test-mode
 	 *   0 is returned if it was successful; any other value indicates failure.
+	 * @note Unlike the GUI, wagons are not automatically attached to trains,
+	 *   only to existing free wagons. This means that BuildVehicle can sometimes
+	 *   return an ID indicating success, but IsValidVehicle check will
+	 *   fail. You should use MoveWagon to attach free wagons to trains.
 	 * @note In Test Mode it means you can't assign orders yet to this vehicle,
 	 *   as the vehicle isn't really built yet. Build it for real first before
 	 *   assigning orders.