From fe71cbfc8b72d9cbdaa64b5ab6ffde376b994c8b Mon Sep 17 00:00:00 2001
From: alberth <alberth@openttd.org>
Date: Sat, 5 Feb 2011 16:20:55 +0000
Subject: [PATCH] (svn r21976) -Doc: Document several crash handling functions.

---
 src/roadveh.h       |  2 +-
 src/roadveh_cmd.cpp | 15 +++++++++++++++
 src/train.h         |  2 +-
 src/train_cmd.cpp   |  9 +++++++++
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/roadveh.h b/src/roadveh.h
index 58b7d07507..c10bb15030 100644
--- a/src/roadveh.h
+++ b/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;
diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp
index 44717dda62..b3d196c110 100644
--- a/src/roadveh_cmd.cpp
+++ b/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;
diff --git a/src/train.h b/src/train.h
index 085987a7fd..815aef839e 100644
--- a/src/train.h
+++ b/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;
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
index 883f46faef..506845d596 100644
--- 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 *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;