(svn r21976) -Doc: Document several crash handling functions.

src/roadveh.h

@@ -90,7 +90,7 @@ struct RoadVehicle : public GroundVehicle<RoadVehicle, VEH_ROAD> {
 	uint16 blocked_ctr;
 	byte overtaking;        ///< Set to #RVSB_DRIVE_SIDE when overtaking, otherwise 0.
 	byte overtaking_ctr;    ///< The length of the current overtake attempt.
-	uint16 crashed_ctr;
+	uint16 crashed_ctr;     ///< Animation counter when the vehicle has crashed. @see RoadVehIsCrashed
 	byte reverse_ctr;
 
 	RoadType roadtype;

src/roadveh_cmd.cpp

@@ -415,6 +415,10 @@ FORCEINLINE int RoadVehicle::GetCurrentMaxSpeed() const
 	return max_speed;
 }
 
+/**
+ * Delete last vehicle of a chain road vehicles.
+ * @param v First roadvehicle.
+ */
 static void DeleteLastRoadVeh(RoadVehicle *v)
 {
 	Vehicle *u = v;
@@ -441,6 +445,11 @@ static void RoadVehSetRandomDirection(RoadVehicle *v)
 	} while ((v = v->Next()) != NULL);
 }
 
+/**
+ * Road vehicle chain has crashed.
+ * @param v First roadvehicle.
+ * @return whether the chain still exists.
+ */
 static bool RoadVehIsCrashed(RoadVehicle *v)
 {
 	v->crashed_ctr++;
@@ -457,6 +466,12 @@ static bool RoadVehIsCrashed(RoadVehicle *v)
 	return true;
 }
 
+/**
+ * Check routine whether a road and a train vehicle have collided.
+ * @param v    %Train vehicle to test.
+ * @param data Road vehicle to test.
+ * @return %Train vehicle if the vehicles collided, else \c NULL.
+ */
 static Vehicle *EnumCheckRoadVehCrashTrain(Vehicle *v, void *data)
 {
 	const Vehicle *u = (Vehicle*)data;

src/train.h

@@ -73,7 +73,7 @@ struct Train : public GroundVehicle<Train, VEH_TRAIN> {
 	/* Link between the two ends of a multiheaded engine */
 	Train *other_multiheaded_part;
 
-	uint16 crash_anim_pos;
+	uint16 crash_anim_pos; ///< Crash animation counter.
 
 	uint16 flags;
 	TrackBitsByte track;

src/train_cmd.cpp

@@ -3299,6 +3299,10 @@ static void DeleteLastWagon(Train *v)
 	}
 }
 
+/**
+ * Rotate all vehicles of a (crashed) train chain randomly to animate the crash.
+ * @param v First crashed vehicle.
+ */
 static void ChangeTrainDirRandomly(Train *v)
 {
 	static const DirDiff delta[] = {
@@ -3319,6 +3323,11 @@ static void ChangeTrainDirRandomly(Train *v)
 	} while ((v = v->Next()) != NULL);
 }
 
+/**
+ * Handle a crashed train.
+ * @param v First train vehicle.
+ * @return %Vehicle chain still exists.
+ */
 static bool HandleCrashedTrain(Train *v)
 {
 	int state = ++v->crash_anim_pos;