SCI: Doxygenified some comments

svn-id: r40112

2 files changed, 77 insertions, 79 deletions

diff --git a/engines/sci/gfx/gfx_state_internal.h b/engines/sci/gfx/gfx_state_internal.h
index 5bca9c185f..f4cd610292 100644
--- a/engines/sci/gfx/gfx_state_internal.h
+++ b/engines/sci/gfx/gfx_state_internal.h
@@ -101,21 +101,89 @@ struct GfxWidget {
 public:
 	GfxWidget(gfxw_widget_type_t type);
 
-	/*
+	/**
 	 * The widget automatically removes itself from its owner, if it has one.
 	 * Deleting a container will recursively free all of its
 	 * contents.
 	 */
 	virtual ~GfxWidget();
 
-	// TODO: Replace the following with virtual methods
-	gfxw_point_op *draw; /* Draw widget (if dirty) and anything else required for the display to be consistent */
-	gfxw_op *tag; /* Tag the specified widget */
-	gfxw_op_int *print; /* Prints the widget's contents, using sciprintf. Second parameter is indentation. */
-	gfxw_bin_op *compare_to; /* a.compare_to(a, b) returns <0 if a<b, =0 if a=b and >0 if a>b */
-	gfxw_bin_op *equals; /* a equals b if both cause the same data to be displayed */
-	gfxw_bin_op *should_replace; /* (only if a equals b) Whether b should replace a even though they are equivalent */
-	gfxw_bin_op *superarea_of; /* a superarea_of b <=> for each pixel of b there exists an opaque pixel in a at the same location */
+	/**
+	 * Draws the widget.
+	 *
+	 * The widget is drawn iff it is flagged as dirty. Invoking this operation on
+	 * a container widget will recursively draw all of its contents.
+	 *
+	 * @param pos	The position to draw to (added to the widget's  internal position)
+	 */
+	gfxw_point_op *draw;
+
+	/**
+	 * Tags the specified widget.
+	 *
+	 * If invoked on a container widget, this will also tag all of the container's
+	 * contents (but not the contents' contents!)
+	 */
+	gfxw_op *tag;
+
+	/**
+	 * Prints a string representation of the widget with sciprintf.
+	 *
+	 * Will recursively print all of the widget's contents if the widget contains
+	 * further sub-widgets
+	 *
+	 * @param indentation	Number of double spaces to indent
+	 */
+	gfxw_op_int *print;
+
+	/**
+	 * Compares two comparable widgets by their screen position.
+	 *
+	 * This comparison only applies to some widgets; compare_to(a,a)=0 is not
+	 * guaranteed. It may be used for sorting for all widgets.
+	 *
+	 * @param other	other widget
+	 * @return <0, 0, or >0 if other is, respectively, less than, equal
+	 *          to, or greater than self
+	 */
+	gfxw_bin_op *compare_to;
+
+	/**
+	 * Compares two compareable widgets for equality.
+	 *
+	 * This operation checks whether two widgets describe the same graphical data.
+	 * It is used to determine whether a new widget should be discarded because it
+	 * describes the same graphical data as an old widget that has already been
+	 * drawn. For lists, it also checks whether all contents are in an identical
+	 * order.
+	 *
+	 * @param other	other widget
+	 * @return false if the widgets are not equal, true if they match
+	 */
+	gfxw_bin_op *equals;
+
+	/**
+	 * Determine whether other should replace this even though they are equivalent.
+	 *
+	 * When 'equals' returns true, this means that no new widget will be added.
+	 * However, in some cases newer widgets may contain information that should
+	 * cause the older widget to be removed nonetheless; this is indicated by this
+	 * function.
+	 *
+	 * @param other	other widget
+	 * @return false if this should be kept, true if this should be replaced by the 'other'
+	 */
+	gfxw_bin_op *should_replace;
+
+	/**
+	 * Tests whether drawing this after other would reduce all traces of other.
+	 *
+	 * /a superarea_of b <=> for each pixel of b there exists an opaque pixel in a at the same location
+	 *
+	 * @param other	the widget to compare for containment
+	 * @return	true if this is superarea_of other, false otherwise
+	 */
+	gfxw_bin_op *superarea_of;
 
 	/**
 	 * Sets the visual for the widget
diff --git a/engines/sci/gfx/gfx_widgets.h b/engines/sci/gfx/gfx_widgets.h
index ed36884c1b..251af9f7ed 100644
--- a/engines/sci/gfx/gfx_widgets.h
+++ b/engines/sci/gfx/gfx_widgets.h
@@ -96,76 +96,6 @@ extern Common::Point gfxw_point_zero;
 ** gfx_state_internal.h.
 **
 **
-**
-** -- draw(GfxWidget *self, Common::Point pos)
-** Draws the widget.
-** Parameters: (GfxWidget *) self: self reference
-**             (Common::Point) pos: The position to draw to (added to the widget's
-**                            internal position)
-** Returns   : (int) 0
-** The widget is drawn iff it is flagged as dirty. Invoking this operation on
-** a container widget will recursively draw all of its contents.
-**
-**
-** -- tag(GfxWidget *self)
-** Tags the specified widget
-** Parameters: (GfxWidget *) self: self reference
-** Returns   : (int) 0
-** If invoked on a container widget, this will also tag all of the container's
-** contents (but not the contents' contents!)
-**
-**
-** -- print(GfxWidget *self, int indentation)
-** Prints a string representation of the widget with sciprintf
-** Parameters: (GfxWidget *) self: self reference
-**             (int) indentation: Number of double spaces to indent
-** Returns   ; (int) 0
-** Will recursively print all of the widget's contents if the widget contains
-** further sub-widgets
-**
-**
-** -- compare_to(GfxWidget *self, GfxWidget *other)
-** Compares two compareable widgets by their screen position
-** Parameters: (GfxWidget *) self: self reference
-**             (GfxWidget *) other: other widget
-** Returns   : (int) <0, 0, or >0 if other is, respectively, less than, equal
-**                   to, or greater than self
-** This comparison only applies to some widgets; compare_to(a,a)=0 is not
-** guaranteed. It may be used for sorting for all widgets.
-**
-**
-** -- equals(GfxWidget *self, GfxWidget *other)
-** Compares two compareable widgets for equality
-** Parameters: (GfxWidget *) self: self reference
-**             (GfxWidget *) other: other widget
-** Returns   : (int) 0 if the widgets are not equal, != 0 if they match
-** This operation checks whether two widgets describe the same graphical data.
-** It is used to determine whether a new widget should be discarded because it
-** describes the same graphical data as an old widget that has already been
-** drawn. For lists, it also checks whether all contents are in an identical
-** order.
-**
-**
-** -- should_replace(GfxWidget *self, GfxWidget *other)
-** Compares two compareable widgets for equality
-** Parameters: (GfxWidget *) self: self reference
-**             (GfxWidget *) other: other widget
-** Returns   : (int) 0 if 'self' should be kept, != 0 if it should be replaced
-**             by the 'other'
-** When 'equals' returns true, this means that no new widget will be added.
-** However, in some cases newer widgets may contain information that should
-** cause the older widget to be removed nonetheless; this is indicated by this
-** function.
-**
-**
-** -- superarea_of(GfxWidget *self, GfxWidget *other)
-** Tests whether drawing self after other would reduce all traces of other
-** Parameters: (GfxWidget *) self: self reference
-**             (gxfw_widget_t *) other: The widget to compare for containment
-** Returns   : (int) 1 if self is superarea_of other, 0 otherwise
-**
-**
-**
 ** **************************
 ** ** Container operations **
 ** **************************