(svn r22405) -Document: some more "random-ish" tidbits

src/cmd_helper.h

@@ -14,6 +14,14 @@
 
 #include "core/enum_type.hpp"
 
+/**
+ * Extracts a given type from a value.
+ * @tparam T The type of data we're looking for.
+ * @tparam S The offset in the data.
+ * @tparam N The amount of bits to read.
+ * @tparam U The type of data passed to us.
+ * @param v The data to extract the value from.
+ */
 template<typename T, uint S, uint N, typename U> static inline T Extract(U v)
 {
 	/* Check if there are enough bits in v */

src/main_gui.cpp

@@ -513,6 +513,9 @@ bool IsQuitKey(uint16 keycode)
 
 void ShowSelectGameWindow();
 
+/**
+ * Initialise the default colours (remaps and the likes), and load the main windows.
+ */
 void SetupColoursAndInitialWindow()
 {
 	for (uint i = 0; i != 16; i++) {
@@ -538,6 +541,9 @@ void SetupColoursAndInitialWindow()
 	}
 }
 
+/**
+ * Show the vital in-game windows.
+ */
 void ShowVitalWindows()
 {
 	AllocateToolbar();

src/misc_gui.cpp

@@ -1211,6 +1211,11 @@ void UpdateTextBufferSize(Textbuf *tb)
 	tb->caretxoffs = tb->pixels;
 }
 
+/**
+ * Handle the flashing of the caret.
+ * @param tb The text buffer to handle the caret of.
+ * @return True if the caret state changes.
+ */
 bool HandleCaret(Textbuf *tb)
 {
 	/* caret changed? */

src/station_cmd.cpp

@@ -968,6 +968,13 @@ static inline byte *CreateMulti(byte *layout, int n, byte b)
 	return layout;
 }
 
+/**
+ * Create the station layout for the given number of tracks and platform length.
+ * @param layout    The layout to write to.
+ * @param numtracks The number of tracks to write.
+ * @param plat_len  The length of the platforms.
+ * @param statspec  The specification of the station to (possibly) get the layout from.
+ */
 void GetStationLayout(byte *layout, int numtracks, int plat_len, const StationSpec *statspec)
 {
 	if (statspec != NULL && statspec->lengths >= plat_len &&
@@ -3470,6 +3477,12 @@ static bool CanRemoveRoadWithStop(TileIndex tile, DoCommandFlag flags)
 	return true;
 }
 
+/**
+ * Clear a single tile of a station.
+ * @param tile The tile to clear.
+ * @param flags The DoCommand flags related to the "command".
+ * @return The cost, or error of clearing.
+ */
 CommandCost ClearTile_Station(TileIndex tile, DoCommandFlag flags)
 {
 	if (flags & DC_AUTO) {

src/subsidy_type.h

@@ -14,8 +14,9 @@
 
 #include "core/enum_type.hpp"
 
+/** What part of a subsidy is something? */
 enum PartOfSubsidy {
-	POS_NONE =     0,
+	POS_NONE =     0, ///< nothing
 	POS_SRC = 1 << 0, ///< bit 0 set -> town/industry is source of subsidised path
 	POS_DST = 1 << 1, ///< bit 1 set -> town/industry is destination of subsidised path
 };

src/terraform_gui.cpp

@@ -368,6 +368,11 @@ static const WindowDesc _terraform_desc(
 	_nested_terraform_widgets, lengthof(_nested_terraform_widgets)
 );
 
+/**
+ * Show the toolbar for terraforming in the game.
+ * @param link The toolbar we might want to link to.
+ * @return The allocated toolbar.
+ */
 Window *ShowTerraformToolbar(Window *link)
 {
 	if (!Company::IsValidID(_local_company)) return NULL;
@@ -781,6 +786,10 @@ static const WindowDesc _scen_edit_land_gen_desc(
 	_nested_scen_edit_land_gen_widgets, lengthof(_nested_scen_edit_land_gen_widgets)
 );
 
+/**
+ * Show the toolbar for terraforming in the scenario editor.
+ * @return The allocated toolbar.
+ */
 Window *ShowEditorTerraformToolbar()
 {
 	return AllocateWindowDescFront<ScenarioEditorLandscapeGenerationWindow>(&_scen_edit_land_gen_desc, 0);

src/textbuf_gui.h

@@ -51,7 +51,7 @@ enum QueryStringFlags {
 
 DECLARE_ENUM_AS_BIT_SET(QueryStringFlags)
 
-
+/** Callback procedure for the ShowQuery method. */
 typedef void QueryCallbackProc(Window*, bool);
 
 void ShowQueryString(StringID str, StringID caption, uint max_len, Window *parent, CharSetFilter afilter, QueryStringFlags flags);

src/thread/thread.h

@@ -12,8 +12,10 @@
 #ifndef THREAD_H
 #define THREAD_H
 
+/** Definition of all thread entry functions. */
 typedef void (*OTTDThreadFunc)(void *);
 
+/** Signal used for signalling we knowingly want to end the thread. */
 class OTTDThreadExitSignal { };
 
 /**
@@ -52,6 +54,9 @@ public:
  */
 class ThreadMutex {
 public:
+	/**
+	 * Create a new mutex.
+	 */
 	static ThreadMutex *New();
 
 	/**

src/thread/thread_os2.cpp

@@ -93,8 +93,8 @@ private:
  */
 class ThreadMutex_OS2 : public ThreadMutex {
 private:
-	HMTX mutex;
-	HEV event;
+	HMTX mutex; ///< The mutex.
+	HEV event;  ///< Event for waiting.
 
 public:
 	ThreadMutex_OS2()

src/thread/thread_pthread.cpp

@@ -95,9 +95,9 @@ private:
  */
 class ThreadMutex_pthread : public ThreadMutex {
 private:
-	pthread_mutex_t mutex;
-	pthread_cond_t condition;
-	pthread_mutexattr_t attr;
+	pthread_mutex_t mutex;    ///< The actual mutex.
+	pthread_cond_t condition; ///< Data for conditional waiting.
+	pthread_mutexattr_t attr; ///< Attributes set for the mutex.
 
 public:
 	ThreadMutex_pthread()

src/thread/thread_win32.cpp

@@ -106,8 +106,8 @@ private:
  */
 class ThreadMutex_Win32 : public ThreadMutex {
 private:
-	CRITICAL_SECTION critical_section;
-	HANDLE event;
+	CRITICAL_SECTION critical_section; ///< The critical section we would enter.
+	HANDLE event;                      ///< Event for signalling.
 
 public:
 	ThreadMutex_Win32()

src/tilearea.cpp

@@ -105,8 +105,8 @@ void TileArea::ClampToMap()
 
 /**
  * Construct the iterator.
- * @param begin Tile from where to begin iterating.
- * @param end   Tile where to end the iterating.
+ * @param corner1 Tile from where to begin iterating.
+ * @param corner2 Tile where to end the iterating.
  */
 DiagonalTileIterator::DiagonalTileIterator(TileIndex corner1, TileIndex corner2) : TileIterator(corner2), base_x(TileX(corner2)), base_y(TileY(corner2)), a_cur(0), b_cur(0)
 {

src/tilearea_type.h

@@ -132,9 +132,12 @@ public:
 /** Iterator to iterate over a diagonal area of the map. */
 class DiagonalTileIterator : public TileIterator {
 private:
-	uint base_x, base_y; ///< The base tile x and y coordinates from where the iterating happens.
-	int a_cur, b_cur;    ///< The current (rotated) x and y coordinates of the iteration.
-	int a_max, b_max;    ///< The (rotated) x and y coordinates of the end of the iteration.
+	uint base_x; ///< The base tile x coordinate from where the iterating happens.
+	uint base_y; ///< The base tile y coordinate from where the iterating happens.
+	int a_cur;   ///< The current (rotated) x coordinate of the iteration.
+	int b_cur;   ///< The current (rotated) y coordinate of the iteration.
+	int a_max;   ///< The (rotated) x coordinats of the end of the iteration.
+	int b_max;   ///< The (rotated) y coordinate of the end of the iteration.
 
 public:
 	DiagonalTileIterator(TileIndex begin, TileIndex end);

src/timetable_cmd.cpp

@@ -18,6 +18,13 @@
 
 #include "table/strings.h"
 
+/**
+ * Change/update a particular timetable entry.
+ * @param v            The vehicle to change the timetable of.
+ * @param order_number The index of the timetable in the order list.
+ * @param time         The new time of the timetable entry.
+ * @param is_journey   Whether to set the waiting or travelling time.
+ */
 static void ChangeTimetable(Vehicle *v, VehicleOrderID order_number, uint16 time, bool is_journey)
 {
 	Order *order = v->GetOrder(order_number);
@@ -222,6 +229,11 @@ CommandCost CmdAutofillTimetable(TileIndex tile, DoCommandFlag flags, uint32 p1,
 	return CommandCost();
 }
 
+/**
+ * Update the timetable for the vehicle.
+ * @param v The vehicle to update the timetable for.
+ * @param travelling Whether we just travelled or waited at a station.
+ */
 void UpdateVehicleTimetable(Vehicle *v, bool travelling)
 {
 	uint timetabled = travelling ? v->current_order.travel_time : v->current_order.wait_time;

src/timetable_gui.cpp

@@ -670,6 +670,10 @@ static const WindowDesc _timetable_desc(
 	_nested_timetable_widgets, lengthof(_nested_timetable_widgets)
 );
 
+/**
+ * Show the timetable for a given vehicle.
+ * @param v The vehicle to show the timetable for.
+ */
 void ShowTimetableWindow(const Vehicle *v)
 {
 	DeleteWindowById(WC_VEHICLE_DETAILS, v->index, false);

src/toolbar_gui.cpp

@@ -1906,8 +1906,7 @@ static WindowDesc _toolb_scen_desc(
 	_nested_toolb_scen_widgets, lengthof(_nested_toolb_scen_widgets)
 );
 
-/* --- Allocating the toolbar --- */
-
+/** Allocate the toolbar. */
 void AllocateToolbar()
 {
 	/* Clean old GUI values; railtype is (re)set by rail_gui.cpp */

src/townname.cpp

@@ -989,6 +989,13 @@ static char *MakeCatalanTownName(char *buf, const char *last, uint32 seed)
 }
 
 
+/**
+ * Type for all town name generator functions.
+ * @param buf  The buffer to write the name to.
+ * @param last The last element of the buffer.
+ * @param seed The seed of the town name.
+ * @return The end of the filled buffer.
+ */
 typedef char *TownNameGenerator(char *buf, const char *last, uint32 seed);
 
 /** Contains pointer to generator and minimum buffer size (not incl. terminating '\0') */

src/townname_func.h

@@ -12,10 +12,12 @@
 #ifndef TOWNNAME_FUNC_H
 #define TOWNNAME_FUNC_H
 
+#include "townname_type.h"
+
 char *GenerateTownNameString(char *buf, const char *last, size_t lang, uint32 seed);
-char *GetTownName(char *buff, const struct TownNameParams *par, uint32 townnameparts, const char *last);
-char *GetTownName(char *buff, const struct Town *t, const char *last);
-bool VerifyTownName(uint32 r, const struct TownNameParams *par);
+char *GetTownName(char *buff, const TownNameParams *par, uint32 townnameparts, const char *last);
+char *GetTownName(char *buff, const Town *t, const char *last);
+bool VerifyTownName(uint32 r, const TownNameParams *par);
 bool GenerateTownName(uint32 *townnameparts);
 
 #endif /* TOWNNAME_FUNC_H */

src/townname_type.h

@@ -16,6 +16,7 @@
 #define TOWNNAME_TYPE_H
 
 #include "newgrf_townname.h"
+#include "town_type.h"
 
 /**
  * Struct holding a parameters used to generate town name.
@@ -37,7 +38,7 @@ struct TownNameParams {
 		this->type = grf ? GetGRFTownNameType(town_name - _nb_orig_names) : SPECSTR_TOWNNAME_START + town_name;
 	}
 
-	TownNameParams(const struct Town *t);
+	TownNameParams(const Town *t);
 };
 
 #endif /* TOWNNAME_TYPE_H */

src/train_gui.cpp

@@ -22,6 +22,13 @@
 #include "table/sprites.h"
 #include "table/strings.h"
 
+/**
+ * Callback for building wagons.
+ * @param result The result of the command.
+ * @param tile   The tile the command was executed on.
+ * @param p1 Additional data for the command (for the #CommandProc)
+ * @param p2 Additional data for the command (for the #CommandProc)
+ */
 void CcBuildWagon(const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2)
 {
 	if (result.Failed()) return;

src/transparency.h

@@ -38,7 +38,7 @@ typedef uint TransparencyOptionBits; ///< transparency option bits
 extern TransparencyOptionBits _transparency_opt;
 extern TransparencyOptionBits _transparency_lock;
 extern TransparencyOptionBits _invisibility_opt;
-extern byte _display_opt; ///< What do we want to draw/do?
+extern byte _display_opt;
 
 /**
  * Check if the transparency option bit is set

src/transparency_gui.cpp

@@ -17,10 +17,10 @@
 #include "table/sprites.h"
 #include "table/strings.h"
 
-TransparencyOptionBits _transparency_opt;
-TransparencyOptionBits _transparency_lock;
-TransparencyOptionBits _invisibility_opt;
-byte _display_opt;
+TransparencyOptionBits _transparency_opt;  ///< The bits that should be transparent.
+TransparencyOptionBits _transparency_lock; ///< Prevent these bits from flipping with X.
+TransparencyOptionBits _invisibility_opt;  ///< The bits that should be invisible.
+byte _display_opt; ///< What do we want to draw/do?
 
 /** Widget numbers of the transparency window. */
 enum TransparencyToolbarWidgets {
@@ -169,6 +169,9 @@ static const WindowDesc _transparency_desc(
 	_nested_transparency_widgets, lengthof(_nested_transparency_widgets)
 );
 
+/**
+ * Show the transparency toolbar.
+ */
 void ShowTransparencyToolbar()
 {
 	AllocateWindowDescFront<TransparenciesWindow>(&_transparency_desc, 0);

src/transport_type.h

@@ -14,6 +14,7 @@
 
 #include "core/enum_type.hpp"
 
+/** Type for the company global vehicle unit number. */
 typedef uint16 UnitID;
 
 /** Available types of transport */
@@ -24,14 +25,15 @@ enum TransportType {
 	 * accessing tunnels and bridges. For now, you should just not change
 	 * the values for road and rail.
 	 */
-	TRANSPORT_BEGIN = 0,
+	TRANSPORT_BEGIN = 0, ///< Begin of the iterator.
 	TRANSPORT_RAIL = TRANSPORT_BEGIN, ///< Transport by train
 	TRANSPORT_ROAD,  ///< Transport by road vehicle
 	TRANSPORT_WATER, ///< Transport over water
 	TRANSPORT_AIR,   ///< Transport through air
-	TRANSPORT_END,
-	INVALID_TRANSPORT = 0xff,
+	TRANSPORT_END,   ///< End of iterations.
+	INVALID_TRANSPORT = 0xff, ///< Sentinel for invalid transport types.
 };
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<TransportType> : MakeEnumPropsT<TransportType, byte, TRANSPORT_BEGIN, TRANSPORT_END, INVALID_TRANSPORT, 2> {};
 
 #endif /* TRANSPORT_TYPE_H */

src/tunnelbridge.h

@@ -16,6 +16,8 @@
 
 /**
  * Calculates the length of a tunnel or a bridge (without end tiles)
+ * @param begin The begin of the tunnel or bridge.
+ * @param end   The end of the tunnel or bridge.
  * @return length of bridge/tunnel middle
  */
 static inline uint GetTunnelBridgeLength(TileIndex begin, TileIndex end)

src/tunnelbridge_cmd.cpp

@@ -45,10 +45,10 @@
 #include "table/strings.h"
 #include "table/bridge_land.h"
 
-BridgeSpec _bridge[MAX_BRIDGES];
-TileIndex _build_tunnel_endtile;
+BridgeSpec _bridge[MAX_BRIDGES]; ///< The specification of all bridges.
+TileIndex _build_tunnel_endtile; ///< The end of a tunnel; as hidden return from the tunnel build command for GUI purposes.
 
-/* Z position of the bridge sprites relative to bridge height (downwards) */
+/** Z position of the bridge sprites relative to bridge height (downwards) */
 static const int BRIDGE_Z_START = 3;
 
 /** Reset the data been eventually changed by the grf loaded. */

src/vehicle_type.h

@@ -14,6 +14,7 @@
 
 #include "core/enum_type.hpp"
 
+/** The type all our vehicle IDs have. */
 typedef uint32 VehicleID;
 
 /** Available vehicle types. */
@@ -28,6 +29,7 @@ enum VehicleType {
 	VEH_INVALID = 0xFF, ///< Non-existing type of vehicle.
 };
 DECLARE_POSTFIX_INCREMENT(VehicleType)
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<VehicleType> : MakeEnumPropsT<VehicleType, byte, VEH_TRAIN, VEH_END, VEH_INVALID, 3> {};
 /** It needs to be 8bits, because we save and load it as such */
 typedef SimpleTinyEnumT<VehicleType, byte> VehicleTypeByte;

src/vehiclelist.h

@@ -53,6 +53,7 @@ struct VehicleListIdentifier {
 	VehicleListIdentifier() {}
 };
 
+/** A list of vehicles. */
 typedef SmallVector<const Vehicle *, 32> VehicleList;
 
 bool GenerateVehicleSortList(VehicleList *list, const VehicleListIdentifier &identifier);

src/video/null_v.cpp

@@ -14,6 +14,7 @@
 #include "../blitter/factory.hpp"
 #include "null_v.h"
 
+/** Factory for the null video driver. */
 static FVideoDriver_Null iFVideoDriver_Null;
 
 const char *VideoDriver_Null::Start(const char * const *parm)

src/viewport_type.h

@@ -29,7 +29,7 @@ struct ViewPort {
 	int virtual_width;   ///< width << zoom
 	int virtual_height;  ///< height << zoom
 
-	ZoomLevel zoom;
+	ZoomLevel zoom; ///< The zoom level of the viewport.
 };
 
 /** Margings for the viewport sign */

src/water_map.h

@@ -17,10 +17,10 @@
 
 /** Available water tile types. */
 enum WaterTileType {
-	WATER_TILE_CLEAR, // Plain water.
-	WATER_TILE_COAST, // Coast.
-	WATER_TILE_LOCK,  // Water lock.
-	WATER_TILE_DEPOT, // Water Depot.
+	WATER_TILE_CLEAR, ///< Plain water.
+	WATER_TILE_COAST, ///< Coast.
+	WATER_TILE_LOCK,  ///< Water lock.
+	WATER_TILE_DEPOT, ///< Water Depot.
 };
 
 /** classes of water (for #WATER_TILE_CLEAR water tile type). */
@@ -30,6 +30,7 @@ enum WaterClass {
 	WATER_CLASS_RIVER,   ///< River.
 	WATER_CLASS_INVALID, ///< Used for industry tiles on land (also for oilrig if newgrf says so).
 };
+/** Helper information for extract tool. */
 template <> struct EnumPropsT<WaterClass> : MakeEnumPropsT<WaterClass, byte, WATER_CLASS_SEA, WATER_CLASS_INVALID, WATER_CLASS_INVALID, 2> {};
 
 /** Sections of the water depot. */
@@ -232,7 +233,7 @@ static inline DiagDirection GetShipDepotDirection(TileIndex t)
 
 /**
  * Get the most northern tile of a ship depot.
- * @param tile One of the tiles of the ship depot.
+ * @param t One of the tiles of the ship depot.
  * @return The northern tile of the depot.
  */
 static inline TileIndex GetShipDepotNorthTile(TileIndex t)

src/waypoint_base.h

@@ -14,9 +14,14 @@
 
 #include "base_station_base.h"
 
+/** Representation of a waypoint. */
 struct Waypoint : SpecializedStation<Waypoint, true> {
 	uint16 town_cn;    ///< The N-1th waypoint for this town (consecutive number)
 
+	/**
+	 * Create a waypoint at the given tile.
+	 * @param tile The location of the waypoint.
+	 */
 	Waypoint(TileIndex tile = INVALID_TILE) : SpecializedStation<Waypoint, true>(tile) { }
 	~Waypoint();
 
@@ -62,6 +67,10 @@ struct Waypoint : SpecializedStation<Waypoint, true> {
 	}
 };
 
+/**
+ * Iterate over all waypoints.
+ * @param var The variable used for iteration.
+ */
 #define FOR_ALL_WAYPOINTS(var) FOR_ALL_BASE_STATIONS_OF_TYPE(Waypoint, var)
 
 #endif /* WAYPOINT_BASE_H */

src/waypoint_cmd.cpp

@@ -91,7 +91,7 @@ Axis GetAxisForNewWaypoint(TileIndex tile)
 	}
 }
 
-CommandCost ClearTile_Station(TileIndex tile, DoCommandFlag flags);
+extern CommandCost ClearTile_Station(TileIndex tile, DoCommandFlag flags);
 
 /**
  * Check whether the given tile is suitable for a waypoint.
@@ -366,7 +366,11 @@ CommandCost RemoveBuoy(TileIndex tile, DoCommandFlag flags)
 	return CommandCost(EXPENSES_CONSTRUCTION, _price[PR_CLEAR_WAYPOINT_BUOY]);
 }
 
-
+/**
+ * Check whether the name is unique amongst the waypoints.
+ * @param name The name to check.
+ * @return True iff the name is unique.
+ */
 static bool IsUniqueWaypointName(const char *name)
 {
 	const Waypoint *wp;

src/waypoint_gui.cpp

@@ -150,6 +150,7 @@ public:
 
 };
 
+/** The widgets of the waypoint view. */
 static const NWidgetPart _nested_waypoint_view_widgets[] = {
 	NWidget(NWID_HORIZONTAL),
 		NWidget(WWT_CLOSEBOX, COLOUR_GREY),
@@ -170,6 +171,7 @@ static const NWidgetPart _nested_waypoint_view_widgets[] = {
 	EndContainer(),
 };
 
+/** The description of the waypoint view. */
 static const WindowDesc _waypoint_view_desc(
 	WDP_AUTO, 260, 118,
 	WC_WAYPOINT_VIEW, WC_NONE,
@@ -177,6 +179,10 @@ static const WindowDesc _waypoint_view_desc(
 	_nested_waypoint_view_widgets, lengthof(_nested_waypoint_view_widgets)
 );
 
+/**
+ * Show the window for the given waypoint.
+ * @param wp The waypoint to show the window for.
+ */
 void ShowWaypointWindow(const Waypoint *wp)
 {
 	AllocateWindowDescFront<WaypointWindow>(&_waypoint_view_desc, wp->index);

src/widget.cpp

@@ -1833,6 +1833,7 @@ void NWidgetViewport::UpdateViewportCoordinates(Window *w)
 /**
  * Compute the row of a scrolled widget that a user clicked in.
  * @param clickpos    Vertical position of the mouse click (without taking scrolling into account).
+ * @param w           The window the click was in.
  * @param widget      Widget number of the widget clicked in.
  * @param padding     Amount of empty space between the widget edge and the top of the first row. Default value is \c 0.
  * @param line_height Height of a single row. A negative value means using the vertical resize step of the widget.

src/zoom_type.h

@@ -14,36 +14,37 @@
 
 #include "core/enum_type.hpp"
 
+/** All zoom levels we know. */
 enum ZoomLevel {
 	/* Our possible zoom-levels */
-	ZOOM_LVL_BEGIN  = 0,
-	ZOOM_LVL_NORMAL = 0,
-	ZOOM_LVL_OUT_2X,
-	ZOOM_LVL_OUT_4X,
-	ZOOM_LVL_OUT_8X,
-	ZOOM_LVL_END,
+	ZOOM_LVL_BEGIN  = 0, ///< Begin for iteration.
+	ZOOM_LVL_NORMAL = 0, ///< The normal zoom level.
+	ZOOM_LVL_OUT_2X,     ///< Zoomed 2 times out.
+	ZOOM_LVL_OUT_4X,     ///< Zoomed 4 times out.
+	ZOOM_LVL_OUT_8X,     ///< Zoomed 8 times out.
+	ZOOM_LVL_END,        ///< End for iteration.
 
-	/* Number of zoom levels */
-	ZOOM_LVL_COUNT = ZOOM_LVL_END - ZOOM_LVL_BEGIN,
+	ZOOM_LVL_COUNT = ZOOM_LVL_END - ZOOM_LVL_BEGIN, ///< Number of zoom levels.
 
 	/* Here we define in which zoom viewports are */
-	ZOOM_LVL_VIEWPORT = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_NEWS     = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_INDUSTRY = ZOOM_LVL_OUT_2X,
-	ZOOM_LVL_TOWN     = ZOOM_LVL_OUT_2X,
-	ZOOM_LVL_AIRCRAFT = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_SHIP     = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_TRAIN    = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_ROADVEH  = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_WORLD_SCREENSHOT = ZOOM_LVL_NORMAL,
+	ZOOM_LVL_VIEWPORT = ZOOM_LVL_NORMAL, ///< Default zoom level for viewports.
+	ZOOM_LVL_NEWS     = ZOOM_LVL_NORMAL, ///< Default zoom level for the news messages.
+	ZOOM_LVL_INDUSTRY = ZOOM_LVL_OUT_2X, ///< Default zoom level for the industry view.
+	ZOOM_LVL_TOWN     = ZOOM_LVL_OUT_2X, ///< Default zoom level for the town view.
+	ZOOM_LVL_AIRCRAFT = ZOOM_LVL_NORMAL, ///< Default zoom level for the aircraft view.
+	ZOOM_LVL_SHIP     = ZOOM_LVL_NORMAL, ///< Default zoom level for the ship view.
+	ZOOM_LVL_TRAIN    = ZOOM_LVL_NORMAL, ///< Default zoom level for the train view.
+	ZOOM_LVL_ROADVEH  = ZOOM_LVL_NORMAL, ///< Default zoom level for the road vehicle view.
+	ZOOM_LVL_WORLD_SCREENSHOT = ZOOM_LVL_NORMAL, ///< Default zoom level for the world screen shot.
 
 	ZOOM_LVL_DETAIL   = ZOOM_LVL_OUT_2X, ///< All zoomlevels below or equal to this, will result in details on the screen, like road-work, ...
 
-	ZOOM_LVL_MIN      = ZOOM_LVL_NORMAL,
-	ZOOM_LVL_MAX      = ZOOM_LVL_OUT_8X,
+	ZOOM_LVL_MIN      = ZOOM_LVL_NORMAL, ///< Minimum zoom level.
+	ZOOM_LVL_MAX      = ZOOM_LVL_OUT_8X, ///< Maximum zoom level.
 };
 DECLARE_POSTFIX_INCREMENT(ZoomLevel)
 
+/** Type for storing the zoom level in a byte. */
 typedef SimpleTinyEnumT<ZoomLevel, byte> ZoomLevelByte;
 
 #endif /* ZOOM_TYPE_H */