Doc updates

(bzr r2949)

3 files changed, 192 insertions, 2 deletions

diff --git a/src/ege-adjustment-action.h b/src/ege-adjustment-action.h
index 7462448ff..0fa896879 100644
--- a/src/ege-adjustment-action.h
+++ b/src/ege-adjustment-action.h
@@ -39,6 +39,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/** \file
+ *  GtkAction subclass that represents a GtkAdjustment value.
+ */
+
 /* Note: this file should be kept compilable as both .cpp and .c */
 
 #include <glib.h>
@@ -59,34 +63,92 @@ typedef struct _EgeAdjustmentAction      EgeAdjustmentAction;
 typedef struct _EgeAdjustmentActionClass EgeAdjustmentActionClass;
 typedef struct _EgeAdjustmentActionPrivate EgeAdjustmentActionPrivate;
 
+/**
+ * Instance structure of EgeAdjustmentAction.
+ */
 struct _EgeAdjustmentAction
 {
+    /** Parent instance structure. */
     GtkAction action;
+
+    /** Pointer to private instance data. */
     EgeAdjustmentActionPrivate *private_data;
 };
 
+/**
+ * Class structure of EgeAdjustmentAction.
+ */
 struct _EgeAdjustmentActionClass
 {
+    /** Parent class structure. */
     GtkActionClass parent_class;
 };
 
+/** Standard Gtk type function */
 GType ege_adjustment_action_get_type( void );
 
+/**
+ * Creates a new EgeAdjustmentAction instance.
+ * This is a GtkAction subclass that manages a value stored in a
+ * GtkAdjustment.
+ *
+ * @param adjustment The GtkAdjustment to manage.
+ * @param name Functional name for the action.
+ * @param label Display label for the action.
+ * @param tooltip Tooltip for the action.
+ * @param stock_id Icon id to use.
+ * @param climb_rate Used for created widgets.
+ * @param digits Used for created widgets.
+ */
 EgeAdjustmentAction* ege_adjustment_action_new( GtkAdjustment* adjustment,
                                                 const gchar *name,
                                                 const gchar *label,
                                                 const gchar *tooltip,
                                                 const gchar *stock_id,
                                                 gdouble climb_rate,
-                                                guint digits );
-
+                                                guint digits
+                                                );
+/**
+ * Returns a pointer to the GtkAdjustment represented by the given
+ * EgeAdjustmentAction.
+ *
+ * @param action The action to fetch the GtkAdjustment for.
+ */
 GtkAdjustment* ege_adjustment_action_get_adjustment( EgeAdjustmentAction* action );
 
+/**
+ * Sets the GtkWidget to return focus to.
+ * This is used to be able to transfer focus back out of a toolbar.
+ *
+ * @param action The action to set the widget for.
+ * @param widget The widget to return focus to after editing.
+ * @see ege_adjustment_action_get_focuswidget
+ */
 void ege_adjustment_action_set_focuswidget( EgeAdjustmentAction* action, GtkWidget* widget );
+
+/**
+ * Returns a pointer to the GtkWidget to return focus to after changing
+ * the value.
+ *
+ * @param action The action to fetch the focus widget for.
+ * @returns A pointer to the widget to return focus to, NULL if none set.
+ * @see ege_adjustment_action_set_focuswidget
+ */
 GtkWidget* ege_adjustment_action_get_focuswidget( EgeAdjustmentAction* action );
 
+/**
+ * Set a list of values with labels to explicitly include in menus.
+ *
+ * @param action The action to set explicit entries for.
+ * @param descriptions Array of descriptions to include.
+ *          Descriptions will be matched one-for-one with numbers in the 'values' array.
+ * @param values Array of values to include.
+ *          Values will be matched one-for-one with numbers in the 'descriptions' array.
+ * @param count Number of items in the 'descriptions' and 'values' arrays.
+ */
 void ege_adjustment_action_set_descriptions( EgeAdjustmentAction* action, gchar const** descriptions, gdouble const* values, guint count );
 
+/** Callback type for post-creation 'fixup' pass on generated widgets */
 typedef void (*EgeWidgetFixup)(GtkWidget *widget);
 
 
diff --git a/src/ege-output-action.h b/src/ege-output-action.h
index 4a8b47b12..e626ccd8c 100644
--- a/src/ege-output-action.h
+++ b/src/ege-output-action.h
@@ -39,6 +39,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/** \file
+ *  GtkAction subclass that represents a string for output.
+ */
+
 /* Note: this file should be kept compilable as both .cpp and .c */
 
 #include <glib.h>
@@ -59,25 +63,58 @@ typedef struct _EgeOutputAction      EgeOutputAction;
 typedef struct _EgeOutputActionClass EgeOutputActionClass;
 typedef struct _EgeOutputActionPrivate EgeOutputActionPrivate;
 
+/**
+ * Instance structure of EgeOutputAction.
+ */
 struct _EgeOutputAction
 {
+    /** Parent instance structure. */
     GtkAction action;
+
+    /** Pointer to private instance data. */
     EgeOutputActionPrivate *private_data;
 };
 
+/**
+ * Class structure of EgeOutputAction.
+ */
 struct _EgeOutputActionClass
 {
+    /** Parent class structure. */
     GtkActionClass parent_class;
 };
 
+/** Standard Gtk type function */
 GType ege_output_action_get_type( void );
 
+/**
+ * Creates a new EgeOutputAction instance.
+ * This is a GtkAction subclass that displays a string.
+ *
+ * @param name Functional name for the action.
+ * @param label Display label for the action.
+ * @param tooltip Tooltip for the action.
+ * @param stock_id Icon id to use.
+ */
 EgeOutputAction* ege_output_action_new( const gchar *name,
                                         const gchar *label,
                                         const gchar *tooltip,
                                         const gchar *stock_id );
 
+/**
+ * Return whether or not the displayed text is interpreted as markup.
+ *
+ * @param action The action to fetch the markup state for.
+ * @return True if the text is to be interpreted as markup, false otherwise.
+ */
 gboolean ege_output_action_get_use_markup( EgeOutputAction* action );
+
+/**
+ * Sets whether or not the displayed text is interpreted as markup.
+ *
+ * @param action The action to set the markup state for.
+ * @param setting True if the text is to be interpreted as markup, false otherwise.
+ */
 void ege_output_action_set_use_markup( EgeOutputAction* action, gboolean setting );
 
 G_END_DECLS
diff --git a/src/ege-select-one-action.h b/src/ege-select-one-action.h
index 787a2c171..f3da195d1 100644
--- a/src/ege-select-one-action.h
+++ b/src/ege-select-one-action.h
@@ -39,6 +39,13 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/** \file
+ * GtkAction subclass that represents a set of values the user may select
+ *  one from at a given time.
+ * This can manifest as a popup menu, a ComboBox, a set of toggle buttons,
+ *  etc.
+ */
+
 /* Note: this file should be kept compilable as both .cpp and .c */
 
 #include <glib.h>
@@ -60,38 +67,122 @@ typedef struct _EgeSelectOneAction      EgeSelectOneAction;
 typedef struct _EgeSelectOneActionClass EgeSelectOneActionClass;
 typedef struct _EgeSelectOneActionPrivate EgeSelectOneActionPrivate;
 
+/**
+ * Instance structure of EgeSelectOneAction.
+ */
 struct _EgeSelectOneAction
 {
+    /** Parent instance structure. */
     GtkAction action;
+
+    /** Pointer to private instance data. */
     EgeSelectOneActionPrivate *private_data;
 };
 
+/**
+ * Class structure of EgeSelectOneAction.
+ */
 struct _EgeSelectOneActionClass
 {
+    /** Parent class structure. */
     GtkActionClass parent_class;
+
     void (*changed) (EgeSelectOneAction* action);
 };
 
+/** Standard Gtk type function */
 GType ege_select_one_action_get_type( void );
 
+/**
+ * Creates a new EgeSelectOneAction instance.
+ * This is a GtkAction subclass that represents a set of values the user
+ *  may select one from at a given time.
+ * This can manifest as a popup menu, a ComboBox, a set of toggle buttons,
+ *  etc.
+ *
+ * @param name Functional name for the action.
+ * @param label Display label for the action.
+ * @param tooltip Tooltip for the action.
+ * @param stock_id Icon id to use.
+ * @param model the source of choices to present.
+ */
 EgeSelectOneAction* ege_select_one_action_new( const gchar *name,
                                                const gchar *label,
                                                const gchar *tooltip,
                                                const gchar *stock_id,
                                                GtkTreeModel* model );
 
+/**
+ * Returns the index of the currently selected item.
+ *
+ * @param action The action to fetch the selected index for.
+ */
 gint ege_select_one_action_get_active( EgeSelectOneAction* action );
+
+/**
+ * Sets the  currently selected item.
+ *
+ * @param action The action to fetch the selected index for.
+ * @param val index of the item to make selected.
+ */
 void ege_select_one_action_set_active( EgeSelectOneAction* action, gint val );
 
+
+/**
+ * Returns the column used for the display label.
+ *
+ * @param action The action to fetch the label column for.
+ */
 gint ege_select_one_action_get_label_column( EgeSelectOneAction* action );
+
+/**
+ * Sets the column used for the display label.
+ *
+ * @param action The action to set the label column for.
+ * @param col column to use.
+ */
 void ege_select_one_action_set_label_column( EgeSelectOneAction* action, gint col );
 
+
+/**
+ * Returns the column used for the display icon.
+ *
+ * @param action The action to fetch the icon column for.
+ */
 gint ege_select_one_action_get_icon_column( EgeSelectOneAction* action );
+
+/**
+ * Sets the column used for the display icon.
+ *
+ * @param action The action to set the icon column for.
+ * @param col column to use.
+ */
 void ege_select_one_action_set_icon_column( EgeSelectOneAction* action, gint col );
 
+
+/**
+ * Returns the column used for the tooltip.
+ *
+ * @param action The action to fetch the tooltip column for.
+ */
 gint ege_select_one_action_get_tooltip_column( EgeSelectOneAction* action );
+
+/**
+ * Sets the column used for the tooltip.
+ *
+ * @param action The action to set the tooltip column for.
+ * @param col column to use.
+ */
 void ege_select_one_action_set_tooltip_column( EgeSelectOneAction* action, gint col );
 
+
+/**
+ * Sets a hint to be used in determining the display form.
+ * This is the XForms style 'appearance' hint: "full", "compact", "minimal".
+ *
+ * @param action The action to set the tooltip column for.
+ * @param val The value of the appearance hint.
+ */
 void ege_select_one_action_set_appearance( EgeSelectOneAction* action, gchar const* val );