(svn r21270) -Doc: Doxyment updates and additions. Removal of doxyment in code.

9 files changed, 60 insertions, 29 deletions

diff --git a/src/bridge.h b/src/bridge.h
index 5f2c1db59..69462e450 100644
--- a/src/bridge.h
+++ b/src/bridge.h
@@ -33,9 +33,9 @@ enum BridgePieces {
 
 DECLARE_POSTFIX_INCREMENT(BridgePieces)
 
-static const uint MAX_BRIDGES = 13;
+static const uint MAX_BRIDGES = 13; ///< Maximal number of available bridge specs.
 
-typedef uint BridgeType;
+typedef uint BridgeType; ///< Bridge spec number.
 
 /**
  * Struct containing information about a single bridge type
diff --git a/src/bridge_gui.cpp b/src/bridge_gui.cpp
index 1b3058717..7c636928f 100644
--- a/src/bridge_gui.cpp
+++ b/src/bridge_gui.cpp
@@ -39,7 +39,7 @@ struct BuildBridgeData {
 	Money cost;
 };
 
-typedef GUIList<BuildBridgeData> GUIBridgeList;
+typedef GUIList<BuildBridgeData> GUIBridgeList; ///< List of bridges, used in #BuildBridgeWindow.
 
 /**
  * Callback executed after a build Bridge CMD has been called
@@ -63,11 +63,12 @@ enum BuildBridgeSelectionWidgets {
 	BBSW_SCROLLBAR,
 };
 
+/** Window class for handling the bridge-build GUI. */
 class BuildBridgeWindow : public Window {
 private:
 	/* Runtime saved values */
-	static uint16 last_size;
-	static Listing last_sorting;
+	static uint16 last_size;     ///< Last size of the bridge GUI window.
+	static Listing last_sorting; ///< Last setting of the sort.
 
 	/* Constants for sorting the bridges */
 	static const StringID sorter_names[];
@@ -287,19 +288,19 @@ public:
 	}
 };
 
-/* Set the default size of the Build Bridge Window */
+/** Set the default size of the Build Bridge Window. */
 uint16 BuildBridgeWindow::last_size = 4;
-/* Set the default sorting for the bridges */
+/** Set the default sorting for the bridges */
 Listing BuildBridgeWindow::last_sorting = {false, 0};
 
-/* Availible bridge sorting functions */
+/** Available bridge sorting functions. */
 GUIBridgeList::SortFunction * const BuildBridgeWindow::sorter_funcs[] = {
 	&BridgeIndexSorter,
 	&BridgePriceSorter,
 	&BridgeSpeedSorter
 };
 
-/* Names of the sorting functions */
+/** Names of the sorting functions. */
 const StringID BuildBridgeWindow::sorter_names[] = {
 	STR_SORT_BY_NUMBER,
 	STR_SORT_BY_COST,
@@ -307,6 +308,7 @@ const StringID BuildBridgeWindow::sorter_names[] = {
 	INVALID_STRING_ID
 };
 
+/** Widgets of the bridge gui. */
 static const NWidgetPart _nested_build_bridge_widgets[] = {
 	/* Header */
 	NWidget(NWID_HORIZONTAL),
@@ -333,7 +335,7 @@ static const NWidgetPart _nested_build_bridge_widgets[] = {
 	EndContainer(),
 };
 
-/* Window definition for the rail bridge selection window */
+/** Window definition for the rail bridge selection window. */
 static const WindowDesc _build_bridge_desc(
 	WDP_AUTO, 200, 114,
 	WC_BUILD_BRIDGE, WC_BUILD_TOOLBAR,
diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
index a59c018b9..1056f2340 100644
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -1043,10 +1043,10 @@ static void ChopLumberMillTrees(Industry *i)
 {
 	TileIndex tile = i->location.tile;
 
-	if (!IsIndustryCompleted(tile)) return;  ///< Can't proceed if not completed
+	if (!IsIndustryCompleted(tile)) return;  // Can't proceed if not completed.
 
-	if (CircularTileSearch(&tile, 40, SearchLumberMillTrees, NULL)) { ///< 40x40 tiles  to search
-		i->produced_cargo_waiting[0] = min(0xffff, i->produced_cargo_waiting[0] + 45); ///< Found a tree, add according value to waiting cargo
+	if (CircularTileSearch(&tile, 40, SearchLumberMillTrees, NULL)) { // 40x40 tiles  to search.
+		i->produced_cargo_waiting[0] = min(0xffff, i->produced_cargo_waiting[0] + 45); // Found a tree, add according value to waiting cargo.
 	}
 }
 
diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp
index ef96572cc..de051ad24 100644
--- a/src/newgrf_industries.cpp
+++ b/src/newgrf_industries.cpp
@@ -506,6 +506,12 @@ CommandCost CheckIfCallBackAllowsCreation(TileIndex tile, IndustryType type, uin
 	NOT_REACHED();
 }
 
+/**
+ * Check with callback #CBM_IND_AVAILABLE whether the industry can be built.
+ * @param type Industry type to check.
+ * @param creation_type Reason to construct a new industry.
+ * @return If the industry has no callback or allows building, \c true is returned. Otherwise, \c false is returned.
+ */
 bool CheckIfCallBackAllowsAvailability(IndustryType type, IndustryAvailabilityCallType creation_type)
 {
 	const IndustrySpec *indspec = GetIndustrySpec(type);
diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp
index fd443fe86..749ab0ea8 100644
--- a/src/newgrf_station.cpp
+++ b/src/newgrf_station.cpp
@@ -89,12 +89,17 @@ struct ETileArea : TileArea {
 };
 
 
-/* Evaluate a tile's position within a station, and return the result a bit-stuffed format.
+/**
+ * Evaluate a tile's position within a station, and return the result in a bit-stuffed format.
  * if not centered: .TNLcCpP, if centered: .TNL..CP
- * T = Tile layout number (#GetStationGfx), N = Number of platforms, L = Length of platforms
- * C = Current platform number from start, c = from end
- * P = Position along platform from start, p = from end
+ * - T = Tile layout number (#GetStationGfx)
+ * - N = Number of platforms
+ * - L = Length of platforms
+ * - C = Current platform number from start, c = from end
+ * - P = Position along platform from start, p = from end
+ * .
  * if centered, C/P start from the centre and c/p are not available.
+ * @return Platform information in bit-stuffed format.
  */
 uint32 GetPlatformInfo(Axis axis, byte tile, int platforms, int length, int x, int y, bool centred)
 {
@@ -129,9 +134,13 @@ uint32 GetPlatformInfo(Axis axis, byte tile, int platforms, int length, int x, i
 }
 
 
-/* Find the end of a railway station, from the tile, in the direction of delta.
- * If check_type is set, we stop if the custom station type changes.
- * If check_axis is set, we stop if the station direction changes.
+/**
+ * Find the end of a railway station, from the \a tile, in the direction of \a delta.
+ * @param tile Start tile.
+ * @param delta Movement direction.
+ * @param check_type Stop when the custom station type changes.
+ * @param check_axis Stop when the station direction changes.
+ * @return Found end of the railway station.
  */
 static TileIndex FindRailStationEnd(TileIndex tile, TileIndexDiff delta, bool check_type, bool check_axis)
 {
@@ -785,8 +794,12 @@ const StationSpec *GetStationSpec(TileIndex t)
 }
 
 
-/* Check if a rail station tile is traversable.
- * XXX This could be cached (during build) in the map array to save on all the dereferencing */
+/**
+ * Check whether a rail station tile is NOT traversable.
+ * @param tile %Tile to test.
+ * @return Station tile is blocked.
+ * @note This could be cached (during build) in the map array to save on all the dereferencing.
+ */
 bool IsStationTileBlocked(TileIndex tile)
 {
 	const StationSpec *statspec = GetStationSpec(tile);
@@ -794,8 +807,12 @@ bool IsStationTileBlocked(TileIndex tile)
 	return statspec != NULL && HasBit(statspec->blocked, GetStationGfx(tile));
 }
 
-/* Check if a rail station tile is electrifiable.
- * XXX This could be cached (during build) in the map array to save on all the dereferencing */
+/**
+ * Check if a rail station tile can be electrified.
+ * @param tile %Tile to test.
+ * @return Tile can be electrified.
+ * @note This could be cached (during build) in the map array to save on all the dereferencing.
+ */
 bool IsStationTileElectrifiable(TileIndex tile)
 {
 	const StationSpec *statspec = GetStationSpec(tile);
diff --git a/src/order_type.h b/src/order_type.h
index 029674bb0..7b252add0 100644
--- a/src/order_type.h
+++ b/src/order_type.h
@@ -27,7 +27,7 @@ static const VehicleOrderID MAX_VEH_ORDER_ID     = INVALID_VEH_ORDER_ID - 1;
 /** Invalid order (sentinel) */
 static const OrderID INVALID_ORDER = 0xFFFF;
 
-/* Order types */
+/** Order types */
 enum OrderType {
 	OT_BEGIN         = 0,
 	OT_NOTHING       = 0,
diff --git a/src/saveload/saveload.cpp b/src/saveload/saveload.cpp
index 8e80ed789..557ea29f1 100644
--- a/src/saveload/saveload.cpp
+++ b/src/saveload/saveload.cpp
@@ -13,8 +13,8 @@
  * are as follows for saving a game (loading is analogous):
  * <ol>
  * <li>initialize the writer by creating a temporary memory-buffer for it
- * <li>go through all to-be saved elements, each 'chunk' (ChunkHandler) prefixed by a label
- * <li>use their description array (SaveLoad) to know what elements to save and in what version
+ * <li>go through all to-be saved elements, each 'chunk' (#ChunkHandler) prefixed by a label
+ * <li>use their description array (#SaveLoad) to know what elements to save and in what version
  *    of the game it was active (used when loading)
  * <li>write all data byte-by-byte to the temporary buffer so it is endian-safe
  * <li>when the buffer is full; flush it to the output (eg save to file) (_sl.buf, _sl.bufp, _sl.bufe)
diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
index 39d22384b..06ad7d982 100644
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -1546,7 +1546,7 @@ CommandCost CmdRemoveFromRailWaypoint(TileIndex start, DoCommandFlag flags, uint
 
 
 /**
- * Remove a rail road station/waypoint
+ * Remove a rail station/waypoint
  * @param st The station/waypoint to remove the rail part from
  * @param flags operation to perform
  * @tparam T the type of station to remove
@@ -1614,7 +1614,7 @@ CommandCost RemoveRailStation(T *st, DoCommandFlag flags)
 }
 
 /**
- * Remove a rail road station
+ * Remove a rail station
  * @param tile TileIndex been queried
  * @param flags operation to perform
  * @return cost or failure of operation
diff --git a/src/viewport_func.h b/src/viewport_func.h
index cc90a93b2..ff59dbb9a 100644
--- a/src/viewport_func.h
+++ b/src/viewport_func.h
@@ -40,6 +40,12 @@ void ZoomInOrOutToCursorWindow(bool in, Window * w);
 Point GetTileZoomCenterWindow(bool in, Window * w);
 void HandleZoomMessage(Window *w, const ViewPort *vp, byte widget_zoom_in, byte widget_zoom_out);
 
+/**
+ * Zoom a viewport as far as possible in the given direction.
+ * @param how Zooming direction.
+ * @param w   Window owning the viewport.
+ * @pre \a how should not be #ZOOM_NONE.
+ */
 static inline void MaxZoomInOut(ZoomStateChange how, Window *w)
 {
 	while (DoZoomInOutWindow(how, w)) {};