Index: wlistitem2a/src/viewport_func.h
===================================================================
--- wlistitem2a/src/viewport_func.h	(revision 12783)
+++ wlistitem2a/src/viewport_func.h	(working copy)
@@ -13,7 +13,7 @@
 void SetSelectionRed(bool);
 
 void DeleteWindowViewport(Window *w);
-void AssignWindowViewport(Window *w, int x, int y, int width, int height, uint32 follow_flags, ZoomLevel zoom);
+void InitializeWindowViewport(Window *w, int x, int y, int width, int height, uint32 follow_flags, ZoomLevel zoom);
 ViewPort *IsPtInWindowViewport(const Window *w, int x, int y);
 Point GetTileBelowCursor();
 void UpdateViewportPosition(Window *w);
Index: wlistitem2a/src/sound.cpp
===================================================================
--- wlistitem2a/src/sound.cpp	(revision 12783)
+++ wlistitem2a/src/sound.cpp	(working copy)
@@ -207,6 +207,14 @@
 	}
 }
 
+/**
+ * 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 @@
 			return;
 		}
 	}
-
 }
 
 void SndPlayTileFx(SoundFx sound, TileIndex tile)
Index: wlistitem2a/src/smallmap_gui.cpp
===================================================================
--- wlistitem2a/src/smallmap_gui.cpp	(revision 12783)
+++ wlistitem2a/src/smallmap_gui.cpp	(working copy)
@@ -1108,15 +1108,15 @@
 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);
+		InitializeWindowViewport(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);
 
 		w->DisableWidget(5);
 		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 @@
 			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 @@
 			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;
Index: wlistitem2a/src/industry_gui.cpp
===================================================================
--- wlistitem2a/src/industry_gui.cpp	(revision 12783)
+++ wlistitem2a/src/industry_gui.cpp	(working copy)
@@ -631,7 +631,7 @@
 		WP(w, indview_d).editbox_line = 0;
 		WP(w, indview_d).clicked_line = 0;
 		WP(w, indview_d).clicked_button = 0;
-		AssignWindowViewport(w, 3, 17, 0xFE, 0x56, GetIndustry(w->window_number)->xy + TileDiffXY(1, 1), ZOOM_LVL_INDUSTRY);
+		InitializeWindowViewport(w, 3, 17, 254, 86, GetIndustry(w->window_number)->xy + TileDiffXY(1, 1), ZOOM_LVL_INDUSTRY);
 	}
 }
 
Index: wlistitem2a/src/engine_func.h
===================================================================
--- wlistitem2a/src/engine_func.h	(revision 12783)
+++ wlistitem2a/src/engine_func.h	(working copy)
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file engine.h */
+/** @file engine_func.h */
 
 #ifndef ENGINE_H
 #define ENGINE_H
Index: wlistitem2a/src/window_func.h
===================================================================
--- wlistitem2a/src/window_func.h	(revision 12783)
+++ wlistitem2a/src/window_func.h	(working copy)
@@ -32,7 +32,6 @@
 void DeleteAllNonVitalWindows();
 void HideVitalWindows();
 void ShowVitalWindows();
-Window **FindWindowZPosition(const Window *w);
 
 void InvalidateWindow(WindowClass cls, WindowNumber number);
 void InvalidateWindowWidget(WindowClass cls, WindowNumber number, byte widget_index);
Index: wlistitem2a/src/window_gui.h
===================================================================
--- wlistitem2a/src/window_gui.h	(revision 12783)
+++ wlistitem2a/src/window_gui.h	(working copy)
@@ -549,15 +549,9 @@
 
 bool IsWindowOfPrototype(const Window *w, const Widget *widget);
 void AssignWidgetToWindow(Window *w, const Widget *widget);
-Window *AllocateWindow(
-							int x,
-							int y,
-							int width,
-							int height,
-							WindowProc *proc,
-							WindowClass cls,
-							const Widget *widget,
-							void *data = NULL);
+Window *AllocateWindow(int x, int y, int width, int height,
+			WindowProc *proc, WindowClass cls, const Widget *widget,
+			void *data = NULL);
 
 Window *AllocateWindowDesc(const WindowDesc *desc, void *data = NULL);
 Window *AllocateWindowDescFront(const WindowDesc *desc, int window_number, void *data = NULL);
@@ -594,12 +588,6 @@
 void DrawSortButtonState(const Window *w, int widget, SortButtonState state);
 
 
-Window *GetCallbackWnd();
-void DeleteNonVitalWindows();
-void DeleteAllNonVitalWindows();
-void HideVitalWindows();
-void ShowVitalWindows();
-Window **FindWindowZPosition(const Window *w);
 
 /* window.cpp */
 extern Window *_z_windows[];
@@ -624,6 +612,13 @@
 	WSM_PRESIZE  = 3,
 };
 
+Window *GetCallbackWnd();
+void DeleteNonVitalWindows();
+void DeleteAllNonVitalWindows();
+void HideVitalWindows();
+void ShowVitalWindows();
+Window **FindWindowZPosition(const Window *w);
+
 void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y);
 
 void ResizeButtons(Window *w, byte left, byte right);
Index: wlistitem2a/src/station_gui.cpp
===================================================================
--- wlistitem2a/src/station_gui.cpp	(revision 12783)
+++ wlistitem2a/src/station_gui.cpp	(working copy)
@@ -184,35 +184,36 @@
 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);
 }
 
 /**
Index: wlistitem2a/src/town_gui.cpp
===================================================================
--- wlistitem2a/src/town_gui.cpp	(revision 12783)
+++ wlistitem2a/src/town_gui.cpp	(working copy)
@@ -396,7 +396,7 @@
 
 	if (w != NULL) {
 		w->flags4 |= WF_DISABLE_VP_SCROLL;
-		AssignWindowViewport(w, 3, 17, 0xFE, 0x56, GetTown(town)->xy, ZOOM_LVL_TOWN);
+		InitializeWindowViewport(w, 3, 17, 254, 86, GetTown(town)->xy, ZOOM_LVL_TOWN);
 	}
 }
 
Index: wlistitem2a/src/window.cpp
===================================================================
--- wlistitem2a/src/window.cpp	(revision 12783)
+++ wlistitem2a/src/window.cpp	(working copy)
@@ -303,6 +303,7 @@
 		}
 	}
 
+	/* 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 @@
 				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 @@
 }
 
 /**
- * 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)
 {
@@ -622,11 +625,11 @@
 {
 	Window* const *wz;
 
-	for (wz = _z_windows;; wz++) {
+	FOR_ALL_WINDOWS(wz) {
 		Window *w = *wz;
-		assert(wz < _last_z_window);
 		if (w->window_class != WC_MAIN_WINDOW && !IsVitalWindow(w)) return w;
 	}
+	NOT_REACHED();
 }
 
 bool IsWindowOfPrototype(const Window *w, const Widget *widget)
@@ -1018,9 +1021,7 @@
  * @return a pointer to the found window if any, NULL otherwise */
 Window *FindWindowFromPt(int x, int y)
 {
-	Window* const *wz;
-
-	for (wz = _last_z_window; wz != _z_windows;) {
+	for (Window* const *wz = _last_z_window; wz != _z_windows;) {
 		Window *w = *--wz;
 		if (IsInsideBS(x, w->left, w->width) && IsInsideBS(y, w->top, w->height)) {
 			return w;
@@ -1038,6 +1039,7 @@
 	IConsoleClose();
 
 	_last_z_window = _z_windows;
+	_mouseover_last_w = NULL;
 	_no_scroll = 0;
 }
 
@@ -1605,7 +1607,6 @@
 {
 	bool bring_to_front = false;
 	Window* const *wz;
-	Window* const *uz;
 
 	if (w->window_class == WC_MAIN_WINDOW ||
 			IsVitalWindow(w) ||
@@ -1615,7 +1616,7 @@
 	}
 
 	wz = FindWindowZPosition(w);
-	for (uz = wz; ++uz != _last_z_window;) {
+	for (Window* const *uz = wz; ++uz != _last_z_window;) {
 		Window *u = *uz;
 
 		/* A modal child will prevent the activation of the parent window */
@@ -1789,9 +1790,6 @@
 	}
 }
 
-extern void UpdateTileSelection();
-extern bool VpHandlePlaceSizingDrag();
-
 /**
  * Local counter that is incremented each time an mouse input event is detected.
  * The counter is used to stop auto-scrolling.
@@ -1852,6 +1850,9 @@
 	TIME_BETWEEN_DOUBLE_CLICK = 500, ///< Time between 2 left clicks before it becoming a double click, in ms
 };
 
+extern void UpdateTileSelection();
+extern bool VpHandlePlaceSizingDrag();
+
 void MouseLoop(MouseClick click, int mousewheel)
 {
 	int x,y;
@@ -2064,8 +2065,9 @@
 }
 
 /**
- * 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 +2079,7 @@
 	}
 }
 
-/*
+/**
  * 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 +2097,7 @@
 	}
 }
 
-/*
+/**
  * Mark all windows of a particular class as dirty (in need of repainting)
  * @param cls Window class
  */
@@ -2119,7 +2121,7 @@
 }
 
 /**
- * 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
  */
@@ -2151,13 +2153,17 @@
  */
 void CallWindowTickEvent()
 {
-	Window* const *wz;
-
-	for (wz = _last_z_window; wz != _z_windows;) {
+	for (Window* const *wz = _last_z_window; wz != _z_windows;) {
 		CallWindowEventNP(*--wz, WE_TICK);
 	}
 }
 
+/**
+ * Try to delete a non-vital window.
+ * Non-vital windows are windows other than the game selection, main toolbar,
+ * status bar, toolbar menu, and tooltip windows. Stickied windows are also
+ * considered vital.
+ */
 void DeleteNonVitalWindows()
 {
 	Window* const *wz;
Index: wlistitem2a/src/news_gui.cpp
===================================================================
--- wlistitem2a/src/news_gui.cpp	(revision 12783)
+++ wlistitem2a/src/news_gui.cpp	(working copy)
@@ -476,7 +476,7 @@
 			_news_type13_desc.top = top;
 			w = AllocateWindowDesc(&_news_type13_desc);
 			if (ni->flags & NF_VIEWPORT) {
-				AssignWindowViewport(w, 2, 58, 0x1AA, 0x6E,
+				InitializeWindowViewport(w, 2, 58, 426, 110,
 					ni->data_a | (ni->flags & NF_VEHICLE ? 0x80000000 : 0), ZOOM_LVL_NEWS);
 			}
 			break;
@@ -485,7 +485,7 @@
 			_news_type2_desc.top = top;
 			w = AllocateWindowDesc(&_news_type2_desc);
 			if (ni->flags & NF_VIEWPORT) {
-				AssignWindowViewport(w, 2, 58, 0x1AA, 0x46,
+				InitializeWindowViewport(w, 2, 58, 426, 70,
 					ni->data_a | (ni->flags & NF_VEHICLE ? 0x80000000 : 0), ZOOM_LVL_NEWS);
 			}
 			break;
@@ -494,7 +494,7 @@
 			_news_type0_desc.top = top;
 			w = AllocateWindowDesc(&_news_type0_desc);
 			if (ni->flags & NF_VIEWPORT) {
-				AssignWindowViewport(w, 3, 17, 0x112, 0x2F,
+				InitializeWindowViewport(w, 3, 17, 274, 47,
 					ni->data_a | (ni->flags & NF_VEHICLE ? 0x80000000 : 0), ZOOM_LVL_NEWS);
 			}
 			break;
Index: wlistitem2a/src/vehicle_gui.cpp
===================================================================
--- wlistitem2a/src/vehicle_gui.cpp	(revision 12783)
+++ wlistitem2a/src/vehicle_gui.cpp	(working copy)
@@ -35,7 +35,6 @@
 #include "settings_type.h"
 #include "widgets/dropdown_func.h"
 #include "order_func.h"
-#include "depot_base.h"
 
 #include "table/sprites.h"
 #include "table/strings.h"
@@ -103,7 +102,11 @@
 	INVALID_STRING_ID
 };
 
-void RebuildVehicleLists()
+/**
+ * Set sort list flag for all vehicle list windows
+ * @param sl_flag Sort list flag to set
+ */
+static void SetVehicleListsFlag(SortListFlags sl_flag)
 {
 	Window* const *wz;
 
@@ -115,7 +118,7 @@
 			case WC_ROADVEH_LIST:
 			case WC_SHIPS_LIST:
 			case WC_AIRCRAFT_LIST:
-				WP(w, vehiclelist_d).l.flags |= VL_REBUILD;
+				WP(w, vehiclelist_d).l.flags |= sl_flag;
 				SetWindowDirty(w);
 				break;
 
@@ -124,25 +127,20 @@
 	}
 }
 
-void ResortVehicleLists()
+/**
+ * Rebuild all vehicle list windows
+ */
+void RebuildVehicleLists()
 {
-	Window* const *wz;
+	SetVehicleListsFlag(VL_REBUILD);
+}
 
-	FOR_ALL_WINDOWS(wz) {
-		Window *w = *wz;
-
-		switch (w->window_class) {
-			case WC_TRAINS_LIST:
-			case WC_ROADVEH_LIST:
-			case WC_SHIPS_LIST:
-			case WC_AIRCRAFT_LIST:
-				WP(w, vehiclelist_d).l.flags |= VL_RESORT;
-				SetWindowDirty(w);
-				break;
-
-			default: break;
-		}
-	}
+/**
+ * Resort all vehicle list windows
+ */
+void ResortVehicleLists()
+{
+	SetVehicleListsFlag(VL_RESORT);
 }
 
 void BuildVehicleList(vehiclelist_d *vl, PlayerID owner, uint16 index, uint16 window_type)
@@ -1753,7 +1751,7 @@
 
 	if (w != NULL) {
 		w->caption_color = v->owner;
-		AssignWindowViewport(w, VV_VIEWPORT_X, VV_VIEWPORT_Y, VV_INITIAL_VIEWPORT_WIDTH,
+		InitializeWindowViewport(w, VV_VIEWPORT_X, VV_VIEWPORT_Y, VV_INITIAL_VIEWPORT_WIDTH,
 												 (v->type == VEH_TRAIN) ? VV_INITIAL_VIEWPORT_HEIGHT_TRAIN : VV_INITIAL_VIEWPORT_HEIGHT,
 												 w->window_number | (1 << 31), _vehicle_view_zoom_levels[v->type]);
 	}
Index: wlistitem2a/src/zoom_func.h
===================================================================
--- wlistitem2a/src/zoom_func.h	(revision 12783)
+++ wlistitem2a/src/zoom_func.h	(working copy)
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file zoom_func.hpp */
+/** @file zoom_func.h */
 
 #ifndef ZOOM_FUNC_H
 #define ZOOM_FUNC_H
Index: wlistitem2a/src/viewport.cpp
===================================================================
--- wlistitem2a/src/viewport.cpp	(revision 12783)
+++ wlistitem2a/src/viewport.cpp	(working copy)
@@ -158,7 +158,19 @@
 	w->viewport = NULL;
 }
 
-void AssignWindowViewport(Window *w, int x, int y,
+/**
+ * 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 InitializeWindowViewport(Window *w, int x, int y,
 	int width, int height, uint32 follow_flags, ZoomLevel zoom)
 {
 	assert(w->viewport == NULL);
@@ -324,7 +336,14 @@
 	}
 }
 
-
+/**
+ * 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 @@
 }
 
 /**
- * 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 @@
 	);
 }
 
+/**
+ * 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;
Index: wlistitem2a/src/main_gui.cpp
===================================================================
--- wlistitem2a/src/main_gui.cpp	(revision 12783)
+++ wlistitem2a/src/main_gui.cpp	(working copy)
@@ -412,7 +412,7 @@
 	int height = _screen.height;
 
 	Window *w = AllocateWindow(0, 0, width, height, MainWindowWndProc, WC_MAIN_WINDOW, NULL);
-	AssignWindowViewport(w, 0, 0, width, height, TileXY(32, 32), ZOOM_LVL_VIEWPORT);
+	InitializeWindowViewport(w, 0, 0, width, height, TileXY(32, 32), ZOOM_LVL_VIEWPORT);
 
 	/* XXX: these are not done */
 	switch (_game_mode) {