(svn r17171) -Doc: Additions and corrections of various doxygen strings.

src/industry_gui.cpp

@@ -32,10 +32,11 @@
 
 bool _ignore_restrictions;
 
+/** Cargo suffix type (for which window is it requested) */
 enum CargoSuffixType {
-	CST_FUND,
+	CST_FUND,  ///< Fund-industry window
-	CST_VIEW,
+	CST_VIEW,  ///< View-industry window
-	CST_DIR,
+	CST_DIR,   ///< Industry-directory window
 };
 
 /**
@@ -46,7 +47,7 @@ enum CargoSuffixType {
  * - 02 - third accepted cargo type
  * - 03 - first produced cargo type
  * - 04 - second produced cargo type
- * @param cst the cargo suffix type (for which window is it requested)
+ * @param cst the cargo suffix type (for which window is it requested). @see CargoSuffixType
  * @param ind the industry (NULL if in fund window)
  * @param ind_type the industry type
  * @param indspec the industry spec

src/news_gui.cpp

@@ -29,7 +29,7 @@
 #define NB_WIDG_PER_SETTING 4
 
 NewsItem _statusbar_news_item;
-bool _news_ticker_sound;
+bool _news_ticker_sound; ///< Make a ticker sound when a news item is published.
 
 static uint MIN_NEWS_AMOUNT = 30;           ///< prefered minimum amount of news messages
 static uint _total_news = 0;                ///< current number of news items
@@ -941,7 +941,7 @@ enum NewsSettingsWidgets {
 static const StringID _message_opt[] = {STR_NEWS_MESSAGES_OFF, STR_NEWS_MESSAGES_SUMMARY, STR_NEWS_MESSAGES_FULL, INVALID_STRING_ID};
 
 struct MessageOptionsWindow : Window {
-	int state;
+	int state; ///< Option value for setting all categories at once.
 
 	MessageOptionsWindow(const WindowDesc *desc) : Window(desc)
 	{

src/viewport.cpp

@@ -2121,6 +2121,10 @@ void SetRedErrorSquare(TileIndex tile)
 	}
 }
 
+/** Highlight \a w by \a h tiles at the cursor.
+ * @param w Width of the highlighted tiles rectangle.
+ * @param h Height of the highlighted tiles rectangle.
+ */
 void SetTileSelectSize(int w, int h)
 {
 	_thd.new_size.x = w * TILE_SIZE;

src/widget.cpp

@@ -825,7 +825,7 @@ void Window::DrawSortButtonState(int widget, SortButtonState state) const
 
 
 /**
- * @defgroup NestedWidgets Hierarchical widgets.
+ * @defgroup NestedWidgets Hierarchical widgets
  * Hierarchical widgets, also known as nested widgets, are widgets stored in a tree. At the leafs of the tree are (mostly) the 'real' widgets
  * visible to the user. At higher levels, widgets get organized in container widgets, until all widgets of the window are merged.
  *

src/widget_type.h

@@ -617,7 +617,7 @@ struct NWidgetPart {
 /**
  * Widget part function for setting the resize step.
  * @param dx Horizontal resize step. 0 means no horizontal resizing.
- * @param dy Vertical resize step. 0 means no horizontal resizing.
+ * @param dy Vertical resize step. 0 means no vertical resizing.
  * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetResize(int16 dx, int16 dy)

src/widgets/dropdown.cpp

@@ -77,9 +77,9 @@ static const NWidgetPart _nested_dropdown_menu_widgets[] = {
 };
 
 struct DropdownWindow : Window {
-	WindowClass parent_wnd_class;
+	WindowClass parent_wnd_class; ///< Parent window class.
-	WindowNumber parent_wnd_num;
+	WindowNumber parent_wnd_num;  ///< Parent window number.
-	byte parent_button;
+	byte parent_button;           ///< Parent widget number where the window is dropped from.
 	DropDownList *list;
 	int selected_index;
 	byte click_delay;
@@ -388,6 +388,7 @@ void ShowDropDownMenu(Window *w, const StringID *strings, int selected, int butt
 /**
  * Delete the drop-down menu from window \a pw
  * @param pw Parent window of the drop-down menu window
+ * @return Parent widget number if the drop-down was found and closed, \c -1 if the window was not found.
  */
 int HideDropDownMenu(Window *pw)
 {

src/window_gui.h

@@ -188,10 +188,11 @@ struct ResizeInfo {
 	uint step_height; ///< Step-size of height resize changes
 };
 
+/** State of a sort direction button. */
 enum SortButtonState {
-	SBS_OFF,
+	SBS_OFF,  ///< Do not sort (with this button).
-	SBS_DOWN,
+	SBS_DOWN, ///< Sort ascending.
-	SBS_UP,
+	SBS_UP,   ///< Sort descending.
 };
 
 /**