(svn r12787) -Documentation: add/fix documentation of some functions. Patch by Alberth.

7 files changed, 71 insertions, 31 deletions

diff --git a/src/engine_func.h b/src/engine_func.h
index 7b5cac1d5..387cf5552 100644
--- a/src/engine_func.h
+++ b/src/engine_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file engine.h */
+/** @file engine_func.h */
 
 #ifndef ENGINE_H
 #define ENGINE_H
diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp
index e4caa9837..6430c7798 100644
--- a/src/smallmap_gui.cpp
+++ b/src/smallmap_gui.cpp
@@ -1108,7 +1108,7 @@ static const Widget _extra_view_port_widgets[] = {
 static void ExtraViewPortWndProc(Window *w, WindowEvent *e)
 {
 	switch (e->event) {
-	case WE_CREATE: /* Disable zoom in button */
+	case WE_CREATE: // Disable zoom in button
 		/* New viewport start at (zero,zero) */
 		AssignWindowViewport(w, 3, 17, w->widget[4].right - w->widget[4].left - 1, w->widget[4].bottom - w->widget[4].top - 1, 0, ZOOM_LVL_VIEWPORT);
 
@@ -1116,7 +1116,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e)
 		break;
 
 	case WE_PAINT:
-		// set the number in the title bar
+		/* set the number in the title bar */
 		SetDParam(0, w->window_number + 1);
 
 		DrawWindowWidgets(w);
@@ -1128,7 +1128,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e)
 			case 5: DoZoomInOutWindow(ZOOM_IN,  w); break;
 			case 6: DoZoomInOutWindow(ZOOM_OUT, w); break;
 
-		case 7: { /* location button (move main view to same spot as this view) 'Paste Location' */
+		case 7: { // location button (move main view to same spot as this view) 'Paste Location'
 			Window *w2 = FindWindowById(WC_MAIN_WINDOW, 0);
 			int x = WP(w, vp_d).scrollpos_x; // Where is the main looking at
 			int y = WP(w, vp_d).scrollpos_y;
@@ -1138,7 +1138,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e)
 			WP(w2, vp_d).dest_scrollpos_y =  y - (w2->viewport->virtual_height - w->viewport->virtual_height) / 2;
 		} break;
 
-		case 8: { /* inverse location button (move this view to same spot as main view) 'Copy Location' */
+		case 8: { // inverse location button (move this view to same spot as main view) 'Copy Location'
 			const Window *w2 = FindWindowById(WC_MAIN_WINDOW, 0);
 			int x = WP(w2, const vp_d).scrollpos_x;
 			int y = WP(w2, const vp_d).scrollpos_y;
diff --git a/src/sound.cpp b/src/sound.cpp
index c5daccae4..a9c0cb801 100644
--- a/src/sound.cpp
+++ b/src/sound.cpp
@@ -207,6 +207,14 @@ void SndCopyToPool()
 	}
 }
 
+/**
+ * Decide 'where' (between left and right speaker) to play the sound effect.
+ * @param sound Sound effect to play
+ * @param left   Left edge of virtual coordinates where the sound is produced
+ * @param right  Right edge of virtual coordinates where the sound is produced
+ * @param top    Top edge of virtual coordinates where the sound is produced
+ * @param bottom Bottom edge of virtual coordinates where the sound is produced
+ */
 static void SndPlayScreenCoordFx(SoundFx sound, int left, int right, int top, int bottom)
 {
 	Window* const *wz;
@@ -231,7 +239,6 @@ static void SndPlayScreenCoordFx(SoundFx sound, int left, int right, int top, in
 			return;
 		}
 	}
-
 }
 
 void SndPlayTileFx(SoundFx sound, TileIndex tile)
diff --git a/src/station_gui.cpp b/src/station_gui.cpp
index 033fad74a..64e993e30 100644
--- a/src/station_gui.cpp
+++ b/src/station_gui.cpp
@@ -184,35 +184,36 @@ struct plstations_d {
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(plstations_d));
 
 /**
- * Set the 'SL_REBUILD' flag for all station lists
+ * Set the station sort flag for all station-list windows.
+ * @param sl_flag Sort list flag to set for all station-list windows
  */
-void RebuildStationLists()
+static void SetStationListsFlag(StationListFlags sl_flag)
 {
 	Window *const *wz;
 
 	FOR_ALL_WINDOWS(wz) {
 		Window *w = *wz;
 		if (w->window_class == WC_STATION_LIST) {
-			WP(w, plstations_d).flags |= SL_REBUILD;
+			WP(w, plstations_d).flags |= sl_flag;
 			SetWindowDirty(w);
 		}
 	}
 }
 
 /**
+ * Set the 'SL_REBUILD' flag for all station lists
+ */
+void RebuildStationLists()
+{
+	SetStationListsFlag(SL_REBUILD);
+}
+
+/**
  * Set the 'SL_RESORT' flag for all station lists
  */
 void ResortStationLists()
 {
-	Window *const *wz;
-
-	FOR_ALL_WINDOWS(wz) {
-		Window *w = *wz;
-		if (w->window_class == WC_STATION_LIST) {
-			WP(w, plstations_d).flags |= SL_RESORT;
-			SetWindowDirty(w);
-		}
-	}
+	SetStationListsFlag(SL_RESORT);
 }
 
 /**
diff --git a/src/viewport.cpp b/src/viewport.cpp
index ad9e140d7..582943b64 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -158,6 +158,18 @@ void DeleteWindowViewport(Window *w)
 	w->viewport = NULL;
 }
 
+/**
+ * Initialize viewport of the window for use.
+ * @param w Window to use/display the viewport in
+ * @param x Offset of left edge of viewport with respect to left edge window \a w
+ * @param y Offset of top edge of viewport with respect to top edge window \a w
+ * @param width Width of the viewport
+ * @param height Height of the viewport
+ * @param follow_flags Flags controlling the viewport.
+ *        - If bit 31 is set, the lower 16 bits are the vehicle that the viewport should follow.
+ *        - If bit 31 is clear, it is a tile position.
+ * @param zoom Zoomlevel to display
+ */
 void AssignWindowViewport(Window *w, int x, int y,
 	int width, int height, uint32 follow_flags, ZoomLevel zoom)
 {
@@ -324,7 +336,14 @@ static void SetViewportPosition(Window *w, int x, int y)
 	}
 }
 
-
+/**
+ * Is a xy position inside the viewport of the window?
+ * @param w Window to examine its viewport
+ * @param x X coordinate of the xy position
+ * @param y Y coordinate of the xy position
+ * @return Pointer to the viewport if the xy position is in the viewport of the window,
+ *         otherwise \c NULL is returned.
+ */
 ViewPort *IsPtInWindowViewport(const Window *w, int x, int y)
 {
 	ViewPort *vp = w->viewport;
@@ -1591,11 +1610,12 @@ void UpdateViewportPosition(Window *w)
 }
 
 /**
- * Marks a viewport as dirty for repaint.
- *
- * @param vp The viewport to mark as dirty
- * @todo documents the missing parameters @c left, @c top, @c right and @c bottom
- * @todo detailed description missing
+ * Marks a viewport as dirty for repaint if it displays (a part of) the area the needs to be repainted.
+ * @param vp     The viewport to mark as dirty
+ * @param left   Left edge of area to repaint
+ * @param top    Top edge of area to repaint
+ * @param right  Right edge of area to repaint
+ * @param bottom Bottom edge of area to repaint
  * @ingroup dirty
  */
 static void MarkViewportDirty(const ViewPort *vp, int left, int top, int right, int bottom)
@@ -1622,6 +1642,14 @@ static void MarkViewportDirty(const ViewPort *vp, int left, int top, int right,
 	);
 }
 
+/**
+ * Mark all viewports that display an area as dirty (in need of repaint).
+ * @param left   Left edge of area to repaint
+ * @param top    Top edge of area to repaint
+ * @param right  Right edge of area to repaint
+ * @param bottom Bottom edge of area to repaint
+ * @ingroup dirty
+ */
 void MarkAllViewportsDirty(int left, int top, int right, int bottom)
 {
 	Window **wz;
diff --git a/src/window.cpp b/src/window.cpp
index 46b0883e7..efb8cdadd 100644
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -303,6 +303,7 @@ static void DrawOverlappedWindow(Window* const *wz, int left, int top, int right
 		}
 	}
 
+	/* Setup blitter, and dispatch a repaint event to window *wz */
 	DrawPixelInfo *dp = _cur_dpi;
 	dp->width = right - left;
 	dp->height = bottom - top;
@@ -334,6 +335,7 @@ void DrawOverlappedWindowForAll(int left, int top, int right, int bottom)
 				bottom > w->top &&
 				left < w->left + w->width &&
 				top < w->top + w->height) {
+			/* Window w intersects with the rectangle => needs repaint */
 			DrawOverlappedWindow(wz, left, top, right, bottom);
 		}
 	}
@@ -398,7 +400,8 @@ Window **FindWindowZPosition(const Window *w)
 }
 
 /**
- * Remove window and all its child windows from the window stack
+ * Remove window and all its child windows from the window stack.
+ * @param w Window to delete
  */
 void DeleteWindow(Window *w)
 {
@@ -2064,8 +2067,9 @@ int GetMenuItemIndex(const Window *w, int x, int y)
 }
 
 /**
- * Mark window data as invalid (in need of re-computing)
- * @param w Window with invalid data
+ * Mark window as dirty (in need of repainting)
+ * @param cls Window class
+ * @param number Window number in that class
  */
 void InvalidateWindow(WindowClass cls, WindowNumber number)
 {
@@ -2077,7 +2081,7 @@ void InvalidateWindow(WindowClass cls, WindowNumber number)
 	}
 }
 
-/*
+/**
  * Mark a particular widget in a particular window as dirty (in need of repainting)
  * @param cls Window class
  * @param number Window number in that class
@@ -2095,7 +2099,7 @@ void InvalidateWindowWidget(WindowClass cls, WindowNumber number, byte widget_in
 	}
 }
 
-/*
+/**
  * Mark all windows of a particular class as dirty (in need of repainting)
  * @param cls Window class
  */
@@ -2119,7 +2123,7 @@ void InvalidateThisWindowData(Window *w)
 }
 
 /**
- * Mark window data the window of a given class and specific window number as invalid (in need of re-computing)
+ * Mark window data of the window of a given class and specific window number as invalid (in need of re-computing)
  * @param cls Window class
  * @param number Window number within the class
  */
diff --git a/src/zoom_func.h b/src/zoom_func.h
index 50dc4dfa3..c6cc51861 100644
--- a/src/zoom_func.h
+++ b/src/zoom_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file zoom_func.hpp */
+/** @file zoom_func.h */
 
 #ifndef ZOOM_FUNC_H
 #define ZOOM_FUNC_H