# HG changeset patch
# User alberth <alberth@openttd.org>
# Date 2011-02-05 16:20:55
# Node ID 04f59d7fdf1869a57fb387e778dc3762b83b161a
# Parent  dd046b8073296c6297f7a26a2c30bc1c6b26d573

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

diff --git a/src/roadveh.h b/src/roadveh.h
--- a/src/roadveh.h
+++ b/src/roadveh.h
@@ -90,7 +90,7 @@ struct RoadVehicle : public GroundVehicl
 	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;
diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp
--- a/src/roadveh_cmd.cpp
+++ b/src/roadveh_cmd.cpp
@@ -415,6 +415,10 @@ FORCEINLINE int RoadVehicle::GetCurrentM
 	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(Ro
 	} 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
 	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;
diff --git a/src/train.h b/src/train.h
--- a/src/train.h
+++ b/src/train.h
@@ -73,7 +73,7 @@ struct Train : public GroundVehicle<Trai
 	/* 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;
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
--- a/src/train_cmd.cpp
+++ b/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
 	} 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;