From 75ccf9de3a4abc4a67a373959013a18321995d88 Mon Sep 17 00:00:00 2001
From: alberth <alberth@openttd.org>
Date: Sun, 26 Jul 2009 12:49:26 +0000
Subject: (svn r16960) -Doc: Added some viewport and vehicle type doxygen
 strings.

---
 src/vehicle_type.h | 17 +++++++++--------
 src/viewport.cpp   | 13 ++++++++++++-
 src/window_gui.h   | 16 ++++++++++------
 3 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/src/vehicle_type.h b/src/vehicle_type.h
index b008e1d87..0b5024c49 100644
--- a/src/vehicle_type.h
+++ b/src/vehicle_type.h
@@ -9,15 +9,16 @@
 
 typedef uint16 VehicleID;
 
+/** Available vehicle types. */
 enum VehicleType {
-	VEH_TRAIN,
-	VEH_ROAD,
-	VEH_SHIP,
-	VEH_AIRCRAFT,
-	VEH_EFFECT,
-	VEH_DISASTER,
+	VEH_TRAIN,          ///< %Train vehicle type.
+	VEH_ROAD,           ///< Road vehicle type.
+	VEH_SHIP,           ///< %Ship vehicle type.
+	VEH_AIRCRAFT,       ///< %Aircraft vehicle type.
+	VEH_EFFECT,         ///< Effect vehicle type (smoke, explosions, sparks, bubbles)
+	VEH_DISASTER,       ///< Disaster vehicle type.
 	VEH_END,
-	VEH_INVALID = 0xFF,
+	VEH_INVALID = 0xFF, ///< Non-existing type of vehicle.
 };
 DECLARE_POSTFIX_INCREMENT(VehicleType);
 /** It needs to be 8bits, because we save and load it as such */
@@ -36,7 +37,7 @@ struct BaseVehicle
 	VehicleTypeByte type;    ///< Type of vehicle
 };
 
-static const VehicleID INVALID_VEHICLE = 0xFFFF;
+static const VehicleID INVALID_VEHICLE = 0xFFFF; ///< Constant representing a non-existing vehicle.
 
 /** Pathfinding option states */
 enum {
diff --git a/src/viewport.cpp b/src/viewport.cpp
index b53905514..3e1932bf2 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1578,6 +1578,10 @@ static inline void ClampViewportToMap(const ViewPort *vp, int &x, int &y)
 	y -= vp->virtual_height / 2;
 }
 
+/**
+ * Update the viewport position being displayed.
+ * @param w %Window owning the viewport.
+ */
 void UpdateViewportPosition(Window *w)
 {
 	const ViewPort *vp = w->viewport;
@@ -2037,7 +2041,14 @@ void PlaceObject()
 }
 
 
-/* scrolls the viewport in a window to a given location */
+/** Scrolls the viewport in a window to a given location.
+ * @param x       Desired x location of the map to scroll to (world coordinate).
+ * @param y       Desired y location of the map to scroll to (world coordinate).
+ * @param z       Desired z location of the map to scroll to (world coordinate). Use \c -1 to scroll to the height of the map at the \a x, \a y location.
+ * @param w       %Window containing the viewport.
+ * @param instant Jump to the location instead of slowly moving to it.
+ * @return Destination of the viewport was changed (to activate other actions when the viewport is already at the desired position).
+ */
 bool ScrollWindowTo(int x, int y, int z, Window *w, bool instant)
 {
 	/* The slope cannot be acquired outside of the map, so make sure we are always within the map. */
diff --git a/src/window_gui.h b/src/window_gui.h
index f44efbcc2..ff806d1f1 100644
--- a/src/window_gui.h
+++ b/src/window_gui.h
@@ -189,14 +189,18 @@ enum SortButtonState {
 };
 
 /**
- * Data structure for a window viewport
+ * Data structure for a window viewport.
+ * A viewport is either following a vehicle (its id in then in #follow_vehicle), or it aims to display a specific
+ * location #dest_scrollpos_x, #dest_scrollpos_y (#follow_vehicle is then #INVALID_VEHICLE).
+ * The actual location being shown is #scrollpos_x, #scrollpos_y.
+ * @see InitializeViewport(), UpdateViewportPosition().
  */
 struct ViewportData : ViewPort {
-	VehicleID follow_vehicle;
-	int32 scrollpos_x;
-	int32 scrollpos_y;
-	int32 dest_scrollpos_x;
-	int32 dest_scrollpos_y;
+	VehicleID follow_vehicle; ///< VehicleID to follow if following a vehicle, #INVALID_VEHICLE otherwise.
+	int32 scrollpos_x;        ///< Currently shown x coordinate (virtual screen coordinate of topleft corner of the viewport).
+	int32 scrollpos_y;        ///< Currently shown y coordinate (virtual screen coordinate of topleft corner of the viewport).
+	int32 dest_scrollpos_x;   ///< Current destination x coordinate to display (virtual screen coordinate of topleft corner of the viewport).
+	int32 dest_scrollpos_y;   ///< Current destination y coordinate to display (virtual screen coordinate of topleft corner of the viewport).
 };
 
 /**
-- 
cgit v1.2.3-54-g00ecf