documented GtkExperimentNavigator widget (and TODOs)

2 files changed, 92 insertions, 7 deletions

diff --git a/lib/gtk-experiment-widgets/gtk-experiment-navigator.c b/lib/gtk-experiment-widgets/gtk-experiment-navigator.c
index d9cb05d..cb94b06 100644
--- a/lib/gtk-experiment-widgets/gtk-experiment-navigator.c
+++ b/lib/gtk-experiment-widgets/gtk-experiment-navigator.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ * GTK widget, extending a \e GtkTreeView, for displaying an experiments
+ * structure for navigational purposes.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -23,18 +29,24 @@ static void time_cell_data_cb(GtkTreeViewColumn *col,
 
 static inline void select_time(GtkExperimentNavigator *navi, gint64 selected_time);
 
+/** @private */
 enum {
 	TIME_SELECTED_SIGNAL,
 	LAST_SIGNAL
 };
 static guint gtk_experiment_navigator_signals[LAST_SIGNAL] = {0};
 
+/**
+ * @private
+ * Enumeration of tree store columns that serves as an Id
+ */
 enum {
 	COL_SECTION_NAME,
 	COL_TIME,
 	NUM_COLS
 };
 
+/** @private */
 GType
 gtk_experiment_navigator_get_type(void)
 {
@@ -74,6 +86,15 @@ gtk_experiment_navigator_class_init(GtkExperimentNavigatorClass *klass)
 			     1, G_TYPE_INT64);
 }
 
+/**
+ * Internal constructor for the \e GtkExperimentNavigator widget.
+ * It has to create and fill the \e GtkTreeStore (MVC model), add view columns
+ * and add cell renderers to the view columns.
+ * It should connect the necessary signals to respond to row activations
+ * (double click) in order to emit the \e time-selected signal.
+ *
+ * @param klass Newly constructed \e GtkExperimentNavigator instance
+ */
 static void
 gtk_experiment_navigator_init(GtkExperimentNavigator *klass)
 {
@@ -92,6 +113,7 @@ gtk_experiment_navigator_init(GtkExperimentNavigator *klass)
 	/*
 	 * Create some sample(!) store rows and content
 	 */
+	/** @todo remove sample code */
 	gtk_tree_store_append(store, &toplevel, NULL);
 	gtk_tree_store_set(store, &toplevel,
 			   COL_SECTION_NAME, "FOO", -1);
@@ -133,9 +155,19 @@ gtk_experiment_navigator_init(GtkExperimentNavigator *klass)
 	/* destroy store/model automatically with view */
 	g_object_unref(store);
 
-	/* TODO */
+	/** @todo better \e TreeViewColumn formatting */
+	/** @todo connect signals to respond to row activations */
 }
 
+/**
+ * Cell data function to invoke when rendering the "Time" column.
+ *
+ * @param col       \e GtkTreeViewColumn to render for
+ * @param renderer  Cell renderer to use for rendering
+ * @param model     \e GtkTreeModel associated with the view
+ * @param iter      Row identifier
+ * @param user_data Callback user data
+ */
 static void
 time_cell_data_cb(GtkTreeViewColumn *col __attribute__((unused)),
 		  GtkCellRenderer *renderer,
@@ -148,11 +180,19 @@ time_cell_data_cb(GtkTreeViewColumn *col __attribute__((unused)),
 	gtk_tree_model_get(model, iter,
 			   COL_TIME, &time_val, -1);
 
-	g_snprintf(buf, sizeof(buf), "%lldms", time_val); /* FIXME */
+	/** @todo Improve readability (e.g. h:mm:ss) */
+	g_snprintf(buf, sizeof(buf), "%lldms", time_val);
 
 	g_object_set(renderer, "text", buf, NULL);
 }
 
+/**
+ * Emit "time-selected" signal on a \e GtkExperimentNavigator instance.
+ * It should be emitted when a row entry was selected.
+ *
+ * @param navi          Widget to emit the signal
+ * @param selected_time Selected time in milliseconds
+ */
 static inline void
 select_time(GtkExperimentNavigator *navi, gint64 selected_time)
 {
@@ -164,24 +204,47 @@ select_time(GtkExperimentNavigator *navi, gint64 selected_time)
  * API
  */
 
+/**
+ * Construct new \e GtkExperimentNavigator widget instance.
+ *
+ * @return New \e GtkExperimentNavigator widget instance
+ */
 GtkWidget *
 gtk_experiment_navigator_new(void)
 {
 	return GTK_WIDGET(g_object_new(GTK_TYPE_EXPERIMENT_NAVIGATOR, NULL));
 }
 
+/**
+ * Fills the \e GtkExperimentNavigator widget with the structure specified
+ * in an experiment-XML file (see session.dtd).
+ * Any existing contents should be cleared.
+ *
+ * @param navi Object instance to display the structure in
+ * @param exp  \e ExperimentReader instance symbolizing the XML-file
+ * @return \e TRUE on error, else \e FALSE
+ */
 gboolean
 gtk_experiment_navigator_load(GtkExperimentNavigator *navi,
 			      ExperimentReader *exp)
 {
-	/* TODO */
+	/** @todo Clear contents, process XML file and fill \e TreeViewStore */
 	return TRUE;
 }
 
+/**
+ * Fills the \e GtkExperimentNavigator widget with the structure specified
+ * in an experiment-XML file (see session.dtd).
+ * Any existing contents should be cleared.
+ *
+ * @param navi Object instance to display the structure in
+ * @param exp  Filename of XML-file to open and use for configuring \e navi
+ * @return \e TRUE on error, else \e FALSE
+ */
 gboolean
 gtk_experiment_navigator_load_filename(GtkExperimentNavigator *navi,
 				       const gchar *exp)
 {
-	/* TODO */
+	/** @todo Clear contents, process XML file and fill \e TreeViewStore */
 	return TRUE;
 }
diff --git a/lib/gtk-experiment-widgets/gtk-experiment-navigator.h b/lib/gtk-experiment-widgets/gtk-experiment-navigator.h
index a3ead44..d6b5d72 100644
--- a/lib/gtk-experiment-widgets/gtk-experiment-navigator.h
+++ b/lib/gtk-experiment-widgets/gtk-experiment-navigator.h
@@ -1,3 +1,9 @@
+/**
+ * @file
+ * Header file necessary to include when using the \e GtkExperimentNavigator
+ * widget.
+ */
+
 #ifndef __GTK_EXPERIMENT_NAVIGATOR_H
 #define __GTK_EXPERIMENT_NAVIGATOR_H
 
@@ -10,6 +16,11 @@ G_BEGIN_DECLS
 
 #define GTK_TYPE_EXPERIMENT_NAVIGATOR \
 	(gtk_experiment_navigator_get_type())
+/**
+ * Cast instance pointer to \e GtkExperimentNavigator
+ *
+ * @param obj Object to cast to \e GtkExperimentNavigator
+ */
 #define GTK_EXPERIMENT_NAVIGATOR(obj) \
 	(G_TYPE_CHECK_INSTANCE_CAST((obj), GTK_TYPE_EXPERIMENT_NAVIGATOR, GtkExperimentNavigator))
 #define GTK_EXPERIMENT_NAVIGATOR_CLASS(klass) \
@@ -21,19 +32,30 @@ G_BEGIN_DECLS
 #define GTK_EXPERIMENT_NAVIGATOR_GET_CLASS(obj) \
 	(G_TYPE_INSTANCE_GET_CLASS((obj), GTK_TYPE_EXPERIMENT_NAVIGATOR, GtkExperimentNavigatorClass))
 
+/**
+ * \e GtkExperimentNavigator instance structure
+ */
 typedef struct _GtkExperimentNavigator {
-	GtkTreeView parent_instance;
+	GtkTreeView parent_instance;	/**< Parent instance structure */
 
-	/* TODO */
+	/** @todo Add necessary attributes */
 } GtkExperimentNavigator;
 
+/**
+ * \e GtkExperimentNavigator class structure
+ */
 typedef struct _GtkExperimentNavigatorClass {
-	GtkTreeViewClass parent_class;
+	GtkTreeViewClass parent_class;	/**< Parent class structure */
 
+	/**
+	 * Callback function to invoke when emitting the "time-selected"
+	 * signal. Do not set manually.
+	 */
 	void (*time_selected)(GtkExperimentNavigator *self,
 			      gint64 selected_time, gpointer user_data);
 } GtkExperimentNavigatorClass;
 
+/** @private */
 GType gtk_experiment_navigator_get_type(void);
 
 /*