(svn r14466) -Doc: remove some obsolete parameters, fix a few parameter names in comments and add a little more doxygen documentation.

10 files changed, 72 insertions, 28 deletions

diff --git a/src/command_type.h b/src/command_type.h
index c990f1a2c..bfe1a00fd 100644
--- a/src/command_type.h
+++ b/src/command_type.h
@@ -64,7 +64,7 @@ public:
 
 	/**
 	 * Multiplies the cost of the command by the given factor.
-	 * @param cost factor to multiply the costs with
+	 * @param factor factor to multiply the costs with
 	 * @return this class
 	 */
 	CommandCost MultiplyCost(int factor)
diff --git a/src/console_gui.cpp b/src/console_gui.cpp
index ebca6f9bf..8d4dfc2cf 100644
--- a/src/console_gui.cpp
+++ b/src/console_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file console.cpp Handling of the in-game console. */
+/** @file console_gui.cpp Handling the GUI of the in-game console. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/fileio.cpp b/src/fileio.cpp
index dc5e9065f..543b76729 100644
--- a/src/fileio.cpp
+++ b/src/fileio.cpp
@@ -1029,7 +1029,7 @@ static uint ScanTar(FileScanner *fs, const char *extension, TarFileList::iterato
 /**
  * Scan for files with the given extention in the given search path.
  * @param extension the extension of files to search for.
- * @param sp        the sub directory to search in.
+ * @param sd        the sub directory to search in.
  * @param tars      whether to search in the tars too.
  * @return the number of found files, i.e. the number of times that
  *         AddFile returned true.
diff --git a/src/network/network_func.h b/src/network/network_func.h
index fac321506..13e45232d 100644
--- a/src/network/network_func.h
+++ b/src/network/network_func.h
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file network_internal.h Variables and function used internally. */
+/** @file network_func.h Network functions used by other parts of OpenTTD. */
 
 #ifndef NETWORK_FUNC_H
 #define NETWORK_FUNC_H
diff --git a/src/vehiclelist.cpp b/src/vehiclelist.cpp
index c6d487bf5..6579397a7 100644
--- a/src/vehiclelist.cpp
+++ b/src/vehiclelist.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file vehicle.cpp Base implementations of all vehicles. */
+/** @file vehiclelist.cpp Lists of vehicles. */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/viewport.cpp b/src/viewport.cpp
index 48045542c..a35c00fe4 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1549,6 +1549,9 @@ static inline void ViewportDraw(const ViewPort *vp, int left, int top, int right
 	ViewportDrawChk(vp, left, top, right, bottom);
 }
 
+/**
+ * Draw the viewport of this window.
+ */
 void Window::DrawViewport() const
 {
 	DrawPixelInfo *dpi = _cur_dpi;
diff --git a/src/widget.cpp b/src/widget.cpp
index 241bb8a2f..9d05a7408 100644
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -204,7 +204,6 @@ void DrawFrameRect(int left, int top, int right, int bottom, int color, FrameFla
 
 /**
  * Paint all widgets of a window.
- * @param w Window
  */
 void Window::DrawWidgets() const
 {
@@ -616,8 +615,8 @@ void ResizeWindowForWidget(Window *w, uint widget, int delta_x, int delta_y)
 	w->resize.height += delta_y;
 }
 
-/** Draw a sort button's up or down arrow symbol.
- * @param w Window of widget
+/**
+ * Draw a sort button's up or down arrow symbol.
  * @param widget Sort button widget
  * @param state State of sort button
  */
diff --git a/src/window.cpp b/src/window.cpp
index 605edbd0d..f12cd573f 100644
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -51,6 +51,13 @@ bool _scrolling_viewport;
 byte _special_mouse_mode;
 
 
+/**
+ * Sets the enabled/disabled status of a list of widgets.
+ * By default, widgets are enabled.
+ * On certain conditions, they have to be disabled.
+ * @param disab_stat status to use ie: disabled = true, enabled = false
+ * @param widgets list of widgets ended by WIDGET_LIST_END
+ */
 void CDECL Window::SetWidgetsDisabledState(bool disab_stat, int widgets, ...)
 {
 	va_list wdg_list;
@@ -65,6 +72,13 @@ void CDECL Window::SetWidgetsDisabledState(bool disab_stat, int widgets, ...)
 	va_end(wdg_list);
 }
 
+/**
+ * Sets the hidden/shown status of a list of widgets.
+ * By default, widgets are visible.
+ * On certain conditions, they have to be hidden.
+ * @param hidden_stat status to use ie. hidden = true, visible = false
+ * @param widgets list of widgets ended by WIDGET_LIST_END
+ */
 void CDECL Window::SetWidgetsHiddenState(bool hidden_stat, int widgets, ...)
 {
 	va_list wdg_list;
@@ -79,6 +93,11 @@ void CDECL Window::SetWidgetsHiddenState(bool hidden_stat, int widgets, ...)
 	va_end(wdg_list);
 }
 
+/**
+ * Sets the lowered/raised status of a list of widgets.
+ * @param lowered_stat status to use ie: lowered = true, raised = false
+ * @param widgets list of widgets ended by WIDGET_LIST_END
+ */
 void CDECL Window::SetWidgetsLoweredState(bool lowered_stat, int widgets, ...)
 {
 	va_list wdg_list;
@@ -93,6 +112,9 @@ void CDECL Window::SetWidgetsLoweredState(bool lowered_stat, int widgets, ...)
 	va_end(wdg_list);
 }
 
+/**
+ * Raise all buttons of the window
+ */
 void Window::RaiseButtons()
 {
 	for (uint i = 0; i < this->widget_count; i++) {
@@ -103,6 +125,10 @@ void Window::RaiseButtons()
 	}
 }
 
+/**
+ * Invalidate a widget, i.e. mark it as being changed and in need of redraw.
+ * @param widget_index the widget to redraw.
+ */
 void Window::InvalidateWidget(byte widget_index) const
 {
 	const Widget *wi = &this->widget[widget_index];
@@ -113,6 +139,11 @@ void Window::InvalidateWidget(byte widget_index) const
 	SetDirtyBlocks(this->left + wi->left, this->top + wi->top, this->left + wi->right + 1, this->top + wi->bottom + 1);
 }
 
+/**
+ * Do all things to make a button look clicked and mark it to be
+ * unclicked in a few ticks.
+ * @param widget the widget to "click"
+ */
 void Window::HandleButtonClick(byte widget)
 {
 	this->LowerWidget(widget);
@@ -340,7 +371,6 @@ void DrawOverlappedWindowForAll(int left, int top, int right, int bottom)
 
 /**
  * Mark entire window as dirty (in need of re-paint)
- * @param w Window to redraw
  * @ingroup dirty
  */
 void Window::SetDirty() const
@@ -792,6 +822,10 @@ void Window::FindWindowPlacementAndResize(int def_width, int def_height)
 	this->SetDirty();
 }
 
+/**
+ * Resize window towards the default size given in the window description.
+ * @param desc the description to get the default size from.
+ */
 void Window::FindWindowPlacementAndResize(const WindowDesc *desc)
 {
 	this->FindWindowPlacementAndResize(desc->default_width, desc->default_height);
diff --git a/src/window_gui.h b/src/window_gui.h
index a1fc73464..0a3755380 100644
--- a/src/window_gui.h
+++ b/src/window_gui.h
@@ -82,7 +82,10 @@ struct Widget {
 	byte type;                        ///< Widget type, see WindowWidgetTypes
 	byte display_flags;               ///< Resize direction, alignment, etc. during resizing. @see ResizeFlags
 	byte color;                       ///< Widget colour, see docs/ottd-colourtext-palette.png
-	int16 left, right, top, bottom;   ///< The position offsets inside the window
+	int16 left;                       ///< The left edge of the widget
+	int16 right;                      ///< The right edge of the widget
+	int16 top;                        ///< The top edge of the widget
+	int16 bottom;                     ///< The bottom edge of the widget
 	uint16 data;                      ///< The String/Image or special code (list-matrixes) of a widget
 	StringID tooltips;                ///< Tooltips that are shown when rightclicking on a widget
 };
@@ -183,9 +186,10 @@ struct ViewportData : ViewPort {
  * Data structure for an opened window
  */
 struct Window : ZeroedMemoryAllocator {
+	/** State whether an event is handled or not */
 	enum EventState {
-		ES_HANDLED,
-		ES_NOT_HANDLED,
+		ES_HANDLED,     ///< The passed event is handled
+		ES_NOT_HANDLED, ///< The passed event is not handled
 	};
 
 protected:
@@ -483,6 +487,7 @@ enum WindowWidgetTypes {
 	WWT_PUSHIMGBTN  = WWT_IMGBTN  | WWB_PUSHBUTTON,
 };
 
+/** Marker for the "end of widgets" in a Window(Desc) widget table. */
 #define WIDGETS_END WWT_LAST,   RESIZE_NONE,     0,     0,     0,     0,     0, 0, STR_NULL
 
 /**
@@ -512,9 +517,8 @@ Window *FindWindowFromPt(int x, int y);
 
 /**
  * Open a new window.
- * @param *desc The pointer to the WindowDesc to be created
+ * @param desc The pointer to the WindowDesc to be created
  * @param window_number the window number of the new window
- * @param data arbitrary data that is send with the WE_CREATE message
  * @return see Window pointer of the newly created window
  */
 template <typename Wcls>
@@ -535,6 +539,8 @@ int GetWidgetFromPos(const Window *w, int x, int y);
 /* window.cpp */
 extern Window *_z_windows[];
 extern Window **_last_z_window;
+
+/** Iterate over all windows */
 #define FOR_ALL_WINDOWS(wz) for (wz = _z_windows; wz != _last_z_window; wz++)
 
 /**
@@ -587,8 +593,8 @@ void SetHScrollCount(Window *w, int num);
  * Sets the enabled/disabled status of a widget.
  * By default, widgets are enabled.
  * On certain conditions, they have to be disabled.
- * @param widget_index : index of this widget in the window
- * @param disab_stat : status to use ie: disabled = true, enabled = false
+ * @param widget_index index of this widget in the window
+ * @param disab_stat status to use ie: disabled = true, enabled = false
  */
 inline void Window::SetWidgetDisabledState(byte widget_index, bool disab_stat)
 {
@@ -598,7 +604,7 @@ inline void Window::SetWidgetDisabledState(byte widget_index, bool disab_stat)
 
 /**
  * Sets a widget to disabled.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::DisableWidget(byte widget_index)
 {
@@ -607,7 +613,7 @@ inline void Window::DisableWidget(byte widget_index)
 
 /**
  * Sets a widget to Enabled.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::EnableWidget(byte widget_index)
 {
@@ -616,7 +622,7 @@ inline void Window::EnableWidget(byte widget_index)
 
 /**
  * Gets the enabled/disabled status of a widget.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  * @return status of the widget ie: disabled = true, enabled = false
  */
 inline bool Window::IsWidgetDisabled(byte widget_index) const
@@ -640,7 +646,7 @@ inline void Window::SetWidgetHiddenState(byte widget_index, bool hidden_stat)
 
 /**
  * Sets a widget hidden.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::HideWidget(byte widget_index)
 {
@@ -649,7 +655,7 @@ inline void Window::HideWidget(byte widget_index)
 
 /**
  * Sets a widget visible.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::ShowWidget(byte widget_index)
 {
@@ -658,7 +664,7 @@ inline void Window::ShowWidget(byte widget_index)
 
 /**
  * Gets the visibility of a widget.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  * @return status of the widget ie: hidden = true, visible = false
  */
 inline bool Window::IsWidgetHidden(byte widget_index) const
@@ -669,8 +675,8 @@ inline bool Window::IsWidgetHidden(byte widget_index) const
 
 /**
  * Sets the lowered/raised status of a widget.
- * @param widget_index : index of this widget in the window
- * @param lowered_stat : status to use ie: lowered = true, raised = false
+ * @param widget_index index of this widget in the window
+ * @param lowered_stat status to use ie: lowered = true, raised = false
  */
 inline void Window::SetWidgetLoweredState(byte widget_index, bool lowered_stat)
 {
@@ -680,7 +686,7 @@ inline void Window::SetWidgetLoweredState(byte widget_index, bool lowered_stat)
 
 /**
  * Invert the lowered/raised  status of a widget.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::ToggleWidgetLoweredState(byte widget_index)
 {
@@ -690,7 +696,7 @@ inline void Window::ToggleWidgetLoweredState(byte widget_index)
 
 /**
  * Marks a widget as lowered.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::LowerWidget(byte widget_index)
 {
@@ -699,7 +705,7 @@ inline void Window::LowerWidget(byte widget_index)
 
 /**
  * Marks a widget as raised.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  */
 inline void Window::RaiseWidget(byte widget_index)
 {
@@ -708,7 +714,7 @@ inline void Window::RaiseWidget(byte widget_index)
 
 /**
  * Gets the lowered state of a widget.
- * @param widget_index : index of this widget in the window
+ * @param widget_index index of this widget in the window
  * @return status of the widget ie: lowered = true, raised= false
  */
 inline bool Window::IsWidgetLowered(byte widget_index) const
diff --git a/src/window_type.h b/src/window_type.h
index 04f03ad68..64d05717a 100644
--- a/src/window_type.h
+++ b/src/window_type.h
@@ -100,6 +100,8 @@ enum WindowClass {
 };
 
 struct Window;
+
+/** Number to differentiate different windows of the same class */
 typedef int32 WindowNumber;
 
 #endif /* WINDOW_TYPE_H */