(svn r16189) -Doc: Additions and improvement of (mainly) nested widgets/widget-parts doxygen docs.

3 files changed, 138 insertions, 24 deletions

diff --git a/src/tile_cmd.h b/src/tile_cmd.h
index e7c178778..e60105900 100644
--- a/src/tile_cmd.h
+++ b/src/tile_cmd.h
@@ -69,7 +69,7 @@ typedef uint GetSlopeZProc(TileIndex tile, uint x, uint y);
 typedef CommandCost ClearTileProc(TileIndex tile, DoCommandFlag flags);
 
 /**
- * Tile callback function signature for obtaining accepted carog of a tile
+ * Tile callback function signature for obtaining accepted cargo of a tile
  * @param tile Tile queried for its accepted cargo
  * @param res  Storage destination of the cargo accepted
  */
diff --git a/src/widget.cpp b/src/widget.cpp
index a861a0d44..e47e942c7 100644
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -12,8 +12,8 @@
 #include "table/sprites.h"
 #include "table/strings.h"
 
-static const char *UPARROW   = "\xEE\x8A\xA0";
-static const char *DOWNARROW = "\xEE\x8A\xAA";
+static const char *UPARROW   = "\xEE\x8A\xA0"; ///< String containing an upwards pointing arrow.
+static const char *DOWNARROW = "\xEE\x8A\xAA"; ///< String containing a downwards pointing arrow.
 
 /**
  * Compute the vertical position of the draggable part of scrollbar
@@ -524,6 +524,13 @@ void Window::DrawWidgets() const
 
 }
 
+/**
+ * Evenly distribute the combined horizontal length of two consecutive widgets.
+ * @param w Window containing the widgets.
+ * @param a Left widget to resize.
+ * @param b Right widget to resize.
+ * @note Widgets are assumed to lie against each other.
+ */
 static void ResizeWidgets(Window *w, byte a, byte b)
 {
 	int16 offset = w->widget[a].left;
@@ -534,6 +541,14 @@ static void ResizeWidgets(Window *w, byte a, byte b)
 	w->widget[b].left  = w->widget[a].right + 1;
 }
 
+/**
+ * Evenly distribute the combined horizontal length of three consecutive widgets.
+ * @param w Window containing the widgets.
+ * @param a Left widget to resize.
+ * @param b Middle widget to resize.
+ * @param c Right widget to resize.
+ * @note Widgets are assumed to lie against each other.
+ */
 static void ResizeWidgets(Window *w, byte a, byte b, byte c)
 {
 	int16 offset = w->widget[a].left;
@@ -638,7 +653,25 @@ void Window::DrawSortButtonState(int widget, SortButtonState state) const
 }
 
 
-/* == Nested 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.
+ *
+ * A leaf widget is one of
+ * - #NWidgetLeaf for widgets visible for the user, or
+ * - #NWidgetSpacer for creating (flexible) empty space between widgets.
+ *
+ * A container widget is one of
+ * - #NWidgetHorizontal for organizing child widgets in a (horizontal) row. The row switches order depending on the language setting (thus supporting
+ *   right-to-left languages),
+ * - #NWidgetHorizontalLTR for organizing child widgets in a (horizontal) row, always in the same order. All childs below this container will also
+ *   never swap order.
+ * - #NWidgetVertical for organizing child widgets underneath each other.
+ * - #NWidgetBackground for adding a background behind its child widget.
+ *
+ * @see NestedWidgetParts
+ */
 
 /**
  * Base class constructor.
@@ -878,6 +911,7 @@ void NWidgetContainer::SetPIP(uint8 pip_pre, uint8 pip_inter, uint8 pip_post)
 	this->pip_post = pip_post;
 }
 
+/** Horizontal container widget. */
 NWidgetHorizontal::NWidgetHorizontal() : NWidgetContainer(NWID_HORIZONTAL)
 {
 }
@@ -986,6 +1020,7 @@ void NWidgetHorizontal::StoreWidgets(Widget *widgets, int length, bool left_movi
 	}
 }
 
+/** Horizontal left-to-right container widget. */
 NWidgetHorizontalLTR::NWidgetHorizontalLTR() : NWidgetHorizontal()
 {
 	this->type = NWID_HORIZONTAL_LTR;
@@ -1001,6 +1036,7 @@ void NWidgetHorizontalLTR::StoreWidgets(Widget *widgets, int length, bool left_m
 	NWidgetHorizontal::StoreWidgets(widgets, length, left_moving, top_moving, false);
 }
 
+/** Vertical container widget. */
 NWidgetVertical::NWidgetVertical() : NWidgetContainer(NWID_VERTICAL)
 {
 }
@@ -1223,10 +1259,11 @@ void NWidgetBackground::StoreWidgets(Widget *widgets, int length, bool left_movi
 
 /**
  * Nested leaf widget.
- * @param tp    Type of leaf widget.
- * @param index Index in the widget array used by the window system.
- * @param data  Data of the widget.
- * @param tip   Tooltip of the widget.
+ * @param tp     Type of leaf widget.
+ * @param colour Colour of the leaf widget.
+ * @param index  Index in the widget array used by the window system.
+ * @param data   Data of the widget.
+ * @param tip    Tooltip of the widget.
  */
 NWidgetLeaf::NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data, StringID tip) : NWidgetCore(tp, colour, true, true, data, tip)
 {
@@ -1314,6 +1351,7 @@ NWidgetLeaf::NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data,
  * @param rtl  Direction of the language.
  * @return Widget array with the converted widgets.
  * @note Caller should release returned widget array with \c free(widgets).
+ * @ingroup NestedWidgets
  */
 Widget *InitializeNWidgets(NWidgetBase *nwid, bool rtl)
 {
@@ -1595,6 +1633,7 @@ static int MakeWidgetTree(const NWidgetPart *parts, int count, NWidgetBase *pare
  * @param parts Array with parts of the widgets.
  * @param count Length of the \a parts array.
  * @return Root of the nested widget tree, a vertical container containing the entire GUI.
+ * @ingroup NestedWidgetParts
  */
 NWidgetContainer *MakeNWidgets(const NWidgetPart *parts, int count)
 {
diff --git a/src/widget_type.h b/src/widget_type.h
index f34be9bf1..0a7772163 100644
--- a/src/widget_type.h
+++ b/src/widget_type.h
@@ -144,6 +144,7 @@ struct Widget {
 
 /**
  * Baseclass for nested widgets.
+ * @ingroup NestedWidgets
  */
 class NWidgetBase : public ZeroedMemoryAllocator {
 public:
@@ -174,7 +175,8 @@ public:
 	uint8 padding_left;   ///< Paddings added to the left of the widget. Managed by parent container widget.
 };
 
-/** Base class for a resizable nested widget. */
+/** Base class for a resizable nested widget.
+ * @ingroup NestedWidgets */
 class NWidgetResizeBase : public NWidgetBase {
 public:
 	NWidgetResizeBase(WidgetType tp, bool fill_x, bool fill_y);
@@ -186,7 +188,8 @@ public:
 	void AssignMinimalPosition(uint x, uint y, uint given_width, uint given_height, bool allow_resize_x, bool allow_resize_y, bool rtl);
 };
 
-/** Base class for a 'real' widget. */
+/** Base class for a 'real' widget.
+ * @ingroup NestedWidgets */
 class NWidgetCore : public NWidgetResizeBase {
 public:
 	NWidgetCore(WidgetType tp, Colours colour, bool def_fill_x, bool def_fill_y, uint16 widget_data, StringID tool_tip);
@@ -203,7 +206,8 @@ public:
 	StringID tool_tip;  ///< Tooltip of the widget. @see Widget::tootips
 };
 
-/** Baseclass for container widgets. */
+/** Baseclass for container widgets.
+ * @ingroup NestedWidgets */
 class NWidgetContainer : public NWidgetBase {
 public:
 	NWidgetContainer(WidgetType tp);
@@ -224,7 +228,8 @@ protected:
 	NWidgetBase *tail; ///< Pointer to last widget in container.
 };
 
-/** Horizontal container. */
+/** Horizontal container.
+ * @ingroup NestedWidgets */
 class NWidgetHorizontal : public NWidgetContainer {
 public:
 	NWidgetHorizontal();
@@ -235,7 +240,8 @@ public:
 	void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl);
 };
 
-/** Horizontal container that doesn't change the direction of the widgets for RTL languages. */
+/** Horizontal container that doesn't change the direction of the widgets for RTL languages.
+ * @ingroup NestedWidgets */
 class NWidgetHorizontalLTR : public NWidgetHorizontal {
 public:
 	NWidgetHorizontalLTR();
@@ -245,7 +251,8 @@ public:
 	void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl);
 };
 
-/** Vertical container */
+/** Vertical container.
+ * @ingroup NestedWidgets */
 class NWidgetVertical : public NWidgetContainer {
 public:
 	NWidgetVertical();
@@ -257,7 +264,8 @@ public:
 };
 
 
-/** Spacer widget */
+/** Spacer widget.
+ * @ingroup NestedWidgets */
 class NWidgetSpacer : public NWidgetResizeBase {
 public:
 	NWidgetSpacer(int length, int height);
@@ -266,7 +274,8 @@ public:
 	void StoreWidgets(Widget *widgets, int length, bool left_moving, bool top_moving, bool rtl);
 };
 
-/** Nested widget with a child. */
+/** Nested widget with a child.
+ * @ingroup NestedWidgets */
 class NWidgetBackground : public NWidgetCore {
 public:
 	NWidgetBackground(WidgetType tp, Colours colour, int index, NWidgetContainer *child = NULL);
@@ -283,7 +292,8 @@ private:
 	NWidgetContainer *child; ///< Child widget.
 };
 
-/** Leaf widget. */
+/** Leaf widget.
+ * @ingroup NestedWidgets */
 class NWidgetLeaf : public NWidgetCore {
 public:
 	NWidgetLeaf(WidgetType tp, Colours colour, int index, uint16 data, StringID tip);
@@ -292,26 +302,71 @@ public:
 Widget *InitializeNWidgets(NWidgetBase *nwid, bool rtl = false);
 bool CompareWidgetArrays(const Widget *orig, const Widget *gen, bool report = true);
 
-/* == Nested widget parts == */
+/**
+ * @defgroup NestedWidgetParts Hierarchical widget parts
+ * To make nested widgets easier to enter, nested widget parts have been created. They allow the tree to be defined in a flat array of parts.
+ *
+ * - Leaf widgets start with a #NWidget(WidgetType tp, Colours col, int16 idx) part.
+ *   Next, specify its properties with one or more of
+ *   - #SetMinimalSize Define the minimal size of the widget.
+ *   - #SetFill Define how the widget may grow to make it nicely.
+ *   - #SetDataTip Define the data and the tooltip of the widget.
+ *   - #SetResize Define how the widget may resize.
+ *   - #SetPadding Create additional space around the widget.
+ *
+ * - To insert a nested widget tree from an external source, nested widget part #NWidgetFunction exists.
+ *   For further customization, the #SetPadding part may be used.
+ *
+ * - Space widgets (#NWidgetSpacer) start with a #NWidget(WidgetType tp), followed by one or more of
+ *   - #SetMinimalSize Define the minimal size of the widget.
+ *   - #SetFill Define how the widget may grow to make it nicely.
+ *   - #SetResize Define how the widget may resize.
+ *   - #SetPadding Create additional space around the widget.
+ *
+ * - Container widgets #NWidgetHorizontal, #NWidgetHorizontalLTR, and #NWidgetVertical, start with a #NWidget(WidgetType tp) part.
+ *   Their properties are derived from the child widgets so they cannot be specified.
+ *   You can however use
+ *   - #SetPadding Define additional padding around the container.
+ *   - #SetPIP Set additional pre/inter/post child widget space.
+ *   .
+ *   Underneath these properties, all child widgets of the container must be defined. To denote that they are childs, add an indent before the nested widget parts of
+ *   the child widgets (it has no meaning for the compiler but it makes the widget parts easier to read).
+ *   Below the last child widget, use an #EndContainer part. This part should be aligned with the #NWidget part that started the container.
+ *
+ * - Background widgets #NWidgetBackground start with a #NWidget(WidgetType tp, Colours col, int16 idx) part.
+ *   What follows depends on how the widget is used.
+ *   - If the widget is used as a leaf widget, that is, to create some space in the window to display a viewport or some text, use the properties of the
+ *     leaf widgets to define how it behaves.
+ *   - If the widget is used a background behind other widgets, it is considered to be a container widgets. Use the properties listed there to define its
+ *     behaviour.
+ *   .
+ *   In both cases, the background widget \b MUST end with a #EndContainer widget part.
+ *
+ * @see NestedWidgets
+ */
 
-/** Widget part for storing data and tooltip information. */
+/** Widget part for storing data and tooltip information.
+ * @ingroup NestedWidgetParts */
 struct NWidgetPartDataTip {
 	uint16 data;      ///< Data value of the widget.
 	StringID tooltip; ///< Tooltip of the widget.
 };
 
-/** Widget part for storing basic widget information. */
+/** Widget part for storing basic widget information.
+ * @ingroup NestedWidgetParts */
 struct NWidgetPartWidget {
 	Colours colour; ///< Widget colour.
 	int16 index;    ///< Widget index in the widget array.
 };
 
-/** Widget part for storing padding. */
+/** Widget part for storing padding.
+ * @ingroup NestedWidgetParts */
 struct NWidgetPartPaddings {
 	uint8 top, right, bottom, left; ///< Paddings for all directions.
 };
 
-/** Widget part for storing pre/inter/post spaces. */
+/** Widget part for storing pre/inter/post spaces.
+ * @ingroup NestedWidgetParts */
 struct NWidgetPartPIP {
 	uint8 pre, inter, post; ///< Amount of space before/between/after child widgets.
 };
@@ -319,7 +374,8 @@ struct NWidgetPartPIP {
 /** Pointer to function returning a nested widget. */
 typedef NWidgetBase *NWidgetFunctionType();
 
-/** Partial widget specification to allow NWidgets to be written nested. */
+/** Partial widget specification to allow NWidgets to be written nested.
+ * @ingroup NestedWidgetParts */
 struct NWidgetPart {
 	WidgetType type;                         ///< Type of the part. @see NWidgetPartType.
 	union {
@@ -338,6 +394,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.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetResize(int16 dx, int16 dy)
 {
@@ -353,6 +410,7 @@ static inline NWidgetPart SetResize(int16 dx, int16 dy)
 /**
  * Widget part function for using a pointer to set the resize step.
  * @param ptr Pointer to horizontal and vertical resize step.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetResize(Point *ptr)
 {
@@ -368,6 +426,7 @@ static inline NWidgetPart SetResize(Point *ptr)
  * Widget part function for setting the minimal size.
  * @param dx Horizontal minimal size.
  * @param dy Vertical minimal size.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetMinimalSize(int16 x, int16 y)
 {
@@ -383,6 +442,7 @@ static inline NWidgetPart SetMinimalSize(int16 x, int16 y)
 /**
  * Widget part function for using a pointer to set the minimal size.
  * @param ptr Pointer to horizontal and vertical minimal size.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetMinimalSize(Point *ptr)
 {
@@ -398,6 +458,7 @@ static inline NWidgetPart SetMinimalSize(Point *ptr)
  * Widget part function for setting filling.
  * @param x_fill Allow horizontal filling from minimal size.
  * @param y_fill Allow vertical filling from minimal size.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetFill(bool x_fill, bool y_fill)
 {
@@ -413,6 +474,7 @@ static inline NWidgetPart SetFill(bool x_fill, bool y_fill)
 /**
  * Widget part function for denoting the end of a container
  * (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart EndContainer()
 {
@@ -426,6 +488,7 @@ static inline NWidgetPart EndContainer()
 /** Widget part function for setting the data and tooltip.
  * @param data Data of the widget.
  * @param tip  Tooltip of the widget.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetDataTip(uint16 data, StringID tip)
 {
@@ -441,6 +504,7 @@ static inline NWidgetPart SetDataTip(uint16 data, StringID tip)
 /**
  * Widget part function for setting the data and tooltip via a pointer.
  * @param ptr Pointer to the data and tooltip of the widget.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetDataTip(NWidgetPartDataTip *ptr)
 {
@@ -453,11 +517,13 @@ static inline NWidgetPart SetDataTip(NWidgetPartDataTip *ptr)
 }
 
 /**
- * Widget part function for setting a padding.
+ * Widget part function for setting additional space around a widget.
+ * Parameters start above the widget, and are specified in clock-wise direction.
  * @param top The padding above the widget.
  * @param right The padding right of the widget.
  * @param bottom The padding below the widget.
  * @param left The padding left of the widget.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetPadding(uint8 top, uint8 right, uint8 bottom, uint8 left)
 {
@@ -475,6 +541,7 @@ static inline NWidgetPart SetPadding(uint8 top, uint8 right, uint8 bottom, uint8
 /**
  * Widget part function for setting a padding.
  * @param padding The padding to use for all directions.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetPadding(uint8 padding)
 {
@@ -486,6 +553,7 @@ static inline NWidgetPart SetPadding(uint8 padding)
  * @param pre The amount of space before the first widget.
  * @param inter The amount of space between widgets.
  * @param post The amount of space after the last widget.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetPIP(uint8 pre, uint8 inter, uint8 post)
 {
@@ -506,6 +574,7 @@ static inline NWidgetPart SetPIP(uint8 pre, uint8 inter, uint8 post)
  * @param idx Index of the widget in the widget array.
  * @note with #WWT_PANEL, #WWT_FRAME, #WWT_INSET, a new container is started.
  *       Child widgets must have a index bigger than the parent index.
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart NWidget(WidgetType tp, Colours col, int16 idx)
 {
@@ -521,6 +590,7 @@ static inline NWidgetPart NWidget(WidgetType tp, Colours col, int16 idx)
 /**
  * Widget part function for starting a new horizontal container, vertical container, or spacer widget.
  * @param tp Type of the new nested widget, #NWID_HORIZONTAL(_LTR), #NWID_VERTICAL, or #NWID_SPACER
+ * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart NWidget(WidgetType tp)
 {
@@ -531,6 +601,11 @@ static inline NWidgetPart NWidget(WidgetType tp)
 	return part;
 }
 
+/**
+ * Obtain a nested widget (sub)tree from an external source.
+ * @param func_ptr Pointer to function that returns the tree.
+ * @ingroup NestedWidgetParts
+ */
 static inline NWidgetPart NWidgetFunction(NWidgetFunctionType *func_ptr)
 {
 	NWidgetPart part;