inline documentation added.

2000-11-24  Miguel de Icaza  <miguel@helixcode.com>

	* e-table-header.c: inline documentation added.

	* e-table-col.c Added inline documentation.

	* e-table-model.c: Added some inline documentation.

svn path=/trunk/; revision=6664

3 files changed, 430 insertions, 152 deletions

diff --git a/widgets/table/e-table-col.c b/widgets/table/e-table-col.c
index 0ac588972f..86bb175234 100644
--- a/widgets/table/e-table-col.c
+++ b/widgets/table/e-table-col.c
@@ -31,9 +31,9 @@ etc_destroy (GtkObject *object)
 	gtk_object_unref (GTK_OBJECT(etc->ecell));
 
 	if (etc->is_pixbuf)
-	  gdk_pixbuf_unref (etc->pixbuf);
+		gdk_pixbuf_unref (etc->pixbuf);
 	else
-	  g_free (etc->text);
+		g_free (etc->text);
 	
 	(*parent_class->destroy)(object);
 }
@@ -89,6 +89,32 @@ e_table_col_init (ETableCol *etc)
 
 E_MAKE_TYPE(e_table_col, "ETableCol", ETableCol, e_table_col_class_init, e_table_col_init, PARENT_TYPE);
 
+/** 
+ * e_table_col_new:
+ * @col_idx: the column we represent in the model
+ * @text: a title for this column
+ * @expansion: FIXME
+ * @min_width: minimum width in pixels for this column
+ * @ecell: the renderer to be used for this column
+ * @compare: comparision function for the elements stored in this column
+ * @resizable: whether the column can be resized interactively by the user
+ *
+ * The ETableCol represents a column to be used inside an ETable.  The
+ * ETableCol objects are inserted inside an ETableHeader (which is just a collection
+ * of ETableCols).  The ETableHeader is the definition of the order in which
+ * columns are shown to the user. 
+ *
+ * The @text argument is the the text that will be shown as a header to the
+ * user. @col_idx reflects where the data for this ETableCol object will
+ * be fetch from an ETableModel.  So even if the user changes the order
+ * of the columns being viewed (the ETableCols in the ETableHeader), the
+ * column will always point to the same column inside the ETableModel.
+ *
+ * The @ecell argument is an ECell object that needs to know how to render the
+ * data in the ETableModel for this specific row. 
+ *
+ * Returns: the newly created ETableCol object.
+ */
 ETableCol *
 e_table_col_new (int col_idx, const char *text, double expansion, int min_width,
 		 ECell *ecell, GCompareFunc compare, gboolean resizable)
@@ -123,6 +149,33 @@ e_table_col_new (int col_idx, const char *text, double expansion, int min_width,
 	return etc;
 }
 
+/** 
+ * e_table_col_new_with_pixbuf:
+ * @col_idx: the column we represent in the model
+ * @pixbuf: the image to be used for the header
+ * @text: a title for this column
+ * @expansion: FIXME
+ * @min_width: minimum width in pixels for this column
+ * @ecell: the renderer to be used for this column
+ * @compare: comparision function for the elements stored in this column
+ * @resizable: whether the column can be resized interactively by the user
+ *
+ * The ETableCol represents a column to be used inside an ETable.  The
+ * ETableCol objects are inserted inside an ETableHeader (which is just a collection
+ * of ETableCols).  The ETableHeader is the definition of the order in which
+ * columns are shown to the user. 
+ *
+ * The @text argument is the the text that will be shown as a header to the
+ * user. @col_idx reflects where the data for this ETableCol object will
+ * be fetch from an ETableModel.  So even if the user changes the order
+ * of the columns being viewed (the ETableCols in the ETableHeader), the
+ * column will always point to the same column inside the ETableModel.
+ *
+ * The @ecell argument is an ECell object that needs to know how to render the
+ * data in the ETableModel for this specific row. 
+ *
+ * Returns: the newly created ETableCol object.
+ */
 ETableCol *
 e_table_col_new_with_pixbuf (int col_idx, GdkPixbuf *pixbuf, double expansion, int min_width,
 			     ECell *ecell, GCompareFunc compare, gboolean resizable)
diff --git a/widgets/table/e-table-header.c b/widgets/table/e-table-header.c
index bc3b7a7e09..8f6012bca4 100644
--- a/widgets/table/e-table-header.c
+++ b/widgets/table/e-table-header.c
@@ -28,13 +28,8 @@ enum {
 	LAST_SIGNAL
 };
 
-static void eth_set_arg (GtkObject *object, GtkArg *arg, guint arg_id);
-static void eth_get_arg (GtkObject *object, GtkArg *arg, guint arg_id);
-static void eth_do_remove (ETableHeader *eth, int idx, gboolean do_unref);
-static void eth_set_width(ETableHeader *eth, int width);
 static void eth_set_size (ETableHeader *eth, int idx, int size);
 static void eth_calc_widths (ETableHeader *eth);
-static void dequeue(ETableHeader *eth, int *column, int *width);
 
 static guint eth_signals [LAST_SIGNAL] = { 0, };
 
@@ -45,28 +40,54 @@ struct two_ints {
 	int width;
 };
 
+static void
+eth_set_width (ETableHeader *eth, int width)
+{
+	eth->width = width;
+}
+
+static void
+dequeue (ETableHeader *eth, int *column, int *width)
+{
+	GSList *head;
+	struct two_ints *store;
+	head = eth->change_queue;
+	eth->change_queue = eth->change_queue->next;
+	if (!eth->change_queue)
+		eth->change_tail = NULL;
+	store = head->data;
+	g_slist_free_1(head);
+	if (column)
+		*column = store->column;
+	if (width)
+		*width = store->width;
+	g_free(store);
+}
+
 static gboolean
-dequeue_idle(ETableHeader *eth)
+dequeue_idle (ETableHeader *eth)
 {
 	int column, width;
-	dequeue(eth, &column, &width);
-	while(eth->change_queue && ((struct two_ints *)eth->change_queue->data)->column == column)
-		dequeue(eth, &column, &width);
+
+	dequeue (eth, &column, &width);
+	while (eth->change_queue && ((struct two_ints *) eth->change_queue->data)->column == column)
+		dequeue (eth, &column, &width);
+
 	if (column == -1)
-		eth_set_width(eth, width);
+		eth_set_width (eth, width);
 	else if (column < eth->col_count)
-		eth_set_size(eth, column, width);
+		eth_set_size (eth, column, width);
 	if (eth->change_queue)
 		return TRUE;
 	else {
-		eth_calc_widths(eth);
+		eth_calc_widths (eth);
 		eth->idle = 0;
 		return FALSE;
 	}
 }
 
 static void
-enqueue(ETableHeader *eth, int column, int width)
+enqueue (ETableHeader *eth, int column, int width)
 {
 	struct two_ints *store;
 	store = g_new(struct two_ints, 1);
@@ -82,22 +103,24 @@ enqueue(ETableHeader *eth, int column, int width)
 	}
 }
 
+void
+e_table_header_set_size (ETableHeader *eth, int idx, int size)
+{
+	g_return_if_fail (eth != NULL);
+	g_return_if_fail (E_IS_TABLE_HEADER (eth));
+
+	enqueue (eth, idx, size);
+}
+
 static void
-dequeue(ETableHeader *eth, int *column, int *width)
+eth_do_remove (ETableHeader *eth, int idx, gboolean do_unref)
 {
-	GSList *head;
-	struct two_ints *store;
-	head = eth->change_queue;
-	eth->change_queue = eth->change_queue->next;
-	if (!eth->change_queue)
-		eth->change_tail = NULL;
-	store = head->data;
-	g_slist_free_1(head);
-	if (column)
-		*column = store->column;
-	if (width)
-		*width = store->width;
-	g_free(store);
+	if (do_unref)
+		gtk_object_unref (GTK_OBJECT (eth->columns [idx]));
+	
+	memmove (&eth->columns [idx], &eth->columns [idx+1],
+		 sizeof (ETableCol *) * (eth->col_count - idx - 1));
+	eth->col_count--;
 }
 
 static void
@@ -131,6 +154,60 @@ eth_destroy (GtkObject *object)
 }
 
 static void
+eth_group_info_changed(ETableSortInfo *info, ETableHeader *eth)
+{
+	enqueue(eth, -1, eth->nominal_width);
+}
+
+static void
+eth_set_arg (GtkObject *object, GtkArg *arg, guint arg_id)
+{
+	ETableHeader *eth = E_TABLE_HEADER (object);
+
+	switch (arg_id) {
+	case ARG_WIDTH:
+		eth->nominal_width = GTK_VALUE_DOUBLE (*arg);
+		enqueue(eth, -1, GTK_VALUE_DOUBLE (*arg));
+		break;
+	case ARG_SORT_INFO:
+		if (eth->sort_info) {
+			if (eth->sort_info_group_change_id)
+				gtk_signal_disconnect(GTK_OBJECT(eth->sort_info), eth->sort_info_group_change_id);
+			gtk_object_unref(GTK_OBJECT(eth->sort_info));
+		}
+		eth->sort_info = E_TABLE_SORT_INFO(GTK_VALUE_OBJECT (*arg));
+		if (eth->sort_info) {
+			gtk_object_ref(GTK_OBJECT(eth->sort_info));
+			eth->sort_info_group_change_id 
+				= gtk_signal_connect(GTK_OBJECT(eth->sort_info), "group_info_changed",
+						     GTK_SIGNAL_FUNC(eth_group_info_changed), eth);
+		}
+		enqueue(eth, -1, eth->nominal_width);
+		break;
+	default:
+		break;
+	}
+}
+
+static void
+eth_get_arg (GtkObject *object, GtkArg *arg, guint arg_id)
+{
+	ETableHeader *eth = E_TABLE_HEADER (object);
+
+	switch (arg_id) {
+	case ARG_SORT_INFO:
+		GTK_VALUE_OBJECT (*arg) = GTK_OBJECT(eth->sort_info);
+		break;
+	case ARG_WIDTH:
+		GTK_VALUE_DOUBLE (*arg) = eth->nominal_width;
+		break;
+	default:
+		arg->type = GTK_TYPE_INVALID;
+		break;
+	}
+}
+
+static void
 e_table_header_class_init (GtkObjectClass *object_class)
 {
 	object_class->destroy = eth_destroy;
@@ -186,29 +263,11 @@ e_table_header_init (ETableHeader *eth)
 	eth->change_tail = NULL;
 }
 
-GtkType
-e_table_header_get_type (void)
-{
-	static GtkType type = 0;
-
-	if (!type){
-		GtkTypeInfo info = {
-			"ETableHeader",
-			sizeof (ETableHeader),
-			sizeof (ETableHeaderClass),
-			(GtkClassInitFunc) e_table_header_class_init,
-			(GtkObjectInitFunc) e_table_header_init,
-			NULL, /* reserved 1 */
-			NULL, /* reserved 2 */
-			(GtkClassInitFunc) NULL
-		};
-
-		type = gtk_type_unique (gtk_object_get_type (), &info);
-	}
-
-	return type;
-}
-
+/**
+ * e_table_header_new:
+ *
+ * Returns: A new @ETableHeader object.
+ */
 ETableHeader *
 e_table_header_new (void)
 {
@@ -220,66 +279,6 @@ e_table_header_new (void)
 }
 
 static void
-eth_group_info_changed(ETableSortInfo *info, ETableHeader *eth)
-{
-	enqueue(eth, -1, eth->nominal_width);
-}
-
-static void
-eth_set_width(ETableHeader *eth, int width)
-{
-	eth->width = width;
-}
-
-static void
-eth_set_arg (GtkObject *object, GtkArg *arg, guint arg_id)
-{
-	ETableHeader *eth = E_TABLE_HEADER (object);
-
-	switch (arg_id) {
-	case ARG_WIDTH:
-		eth->nominal_width = GTK_VALUE_DOUBLE (*arg);
-		enqueue(eth, -1, GTK_VALUE_DOUBLE (*arg));
-		break;
-	case ARG_SORT_INFO:
-		if (eth->sort_info) {
-			if (eth->sort_info_group_change_id)
-				gtk_signal_disconnect(GTK_OBJECT(eth->sort_info), eth->sort_info_group_change_id);
-			gtk_object_unref(GTK_OBJECT(eth->sort_info));
-		}
-		eth->sort_info = E_TABLE_SORT_INFO(GTK_VALUE_OBJECT (*arg));
-		if (eth->sort_info) {
-			gtk_object_ref(GTK_OBJECT(eth->sort_info));
-			eth->sort_info_group_change_id 
-				= gtk_signal_connect(GTK_OBJECT(eth->sort_info), "group_info_changed",
-						     GTK_SIGNAL_FUNC(eth_group_info_changed), eth);
-		}
-		enqueue(eth, -1, eth->nominal_width);
-		break;
-	default:
-		break;
-	}
-}
-
-static void
-eth_get_arg (GtkObject *object, GtkArg *arg, guint arg_id)
-{
-	ETableHeader *eth = E_TABLE_HEADER (object);
-
-	switch (arg_id) {
-	case ARG_SORT_INFO:
-		GTK_VALUE_OBJECT (*arg) = GTK_OBJECT(eth->sort_info);
-		break;
-	case ARG_WIDTH:
-		GTK_VALUE_DOUBLE (*arg) = eth->nominal_width;
-		break;
-	default:
-		arg->type = GTK_TYPE_INVALID;
-		break;
-	}
-}
-
-static void
 eth_update_offsets (ETableHeader *eth)
 {
 	int i;
@@ -302,6 +301,19 @@ eth_do_insert (ETableHeader *eth, int pos, ETableCol *val)
 	eth->col_count ++;
 }
 
+/**
+ * e_table_header_add_column:
+ * eth: the table header to add the column to.
+ * @tc: the ETableCol definition
+ * @pos: position where the ETableCol will go.
+ *
+ * This function adds the @tc ETableCol definition into the @eth ETableHeader
+ * at position @pos.  This is the way you add new ETableCols to the
+ * ETableHeader.
+ *
+ * This function will emit the "structure_change" signal on the @eth object.
+ * The ETableCol is assumed 
+ */
 void
 e_table_header_add_column (ETableHeader *eth, ETableCol *tc, int pos)
 {
@@ -327,6 +339,13 @@ e_table_header_add_column (ETableHeader *eth, ETableCol *tc, int pos)
 	gtk_signal_emit (GTK_OBJECT (eth), eth_signals [STRUCTURE_CHANGE]);
 }
 
+/**
+ * e_table_header_get_column:
+ * @eth: the ETableHeader to query
+ * @column: the column inside the @eth.
+ *
+ * Returns: The ETableCol at @column in the @eth object
+ */
 ETableCol *
 e_table_header_get_column (ETableHeader *eth, int column)
 {
@@ -342,6 +361,12 @@ e_table_header_get_column (ETableHeader *eth, int column)
 	return eth->columns [column];
 }
 
+/**
+ * e_table_header_count:
+ * @eth: the ETableHeader to query
+ *
+ * Returns: the number of columns in this ETableHeader.
+ */
 int
 e_table_header_count (ETableHeader *eth)
 {
@@ -351,6 +376,18 @@ e_table_header_count (ETableHeader *eth)
 	return eth->col_count;
 }
 
+/** 
+ * e_table_header_index:
+ * @eth: the ETableHeader to query
+ * @col: the column to fetch.
+ *
+ * ETableHeaders contain the visual list of columns that the user will
+ * view.  The visible columns will typically map to different columns
+ * in the ETableModel (because the user reordered the data for
+ * example).
+ *
+ * Returns: the column in the model that the @col column
+ * in the ETableHeader points to.  */
 int
 e_table_header_index (ETableHeader *eth, int col)
 {
@@ -361,6 +398,17 @@ e_table_header_index (ETableHeader *eth, int col)
 	return eth->columns [col]->col_idx;
 }
 
+/**
+ * e_table_header_get_index_at:
+ * @eth: the ETableHeader to query
+ * @x_offset: a pixel count from the beginning of the ETableHeader
+ *
+ * This will return the ETableHeader column that would contain
+ * the @x_offset pixel.
+ *
+ * Returns: the column that contains pixel @x_offset, or -1
+ * if no column inside this ETableHeader contains that pixel.
+ */
 int
 e_table_header_get_index_at (ETableHeader *eth, int x_offset)
 {
@@ -380,6 +428,16 @@ e_table_header_get_index_at (ETableHeader *eth, int x_offset)
 	return -1;
 }
 
+/**
+ * e_table_header_get_columns:
+ * @eth: The ETableHeader to query
+ *
+ * Returns: A NULL terminated array of the ETableCols
+ * contained in the ETableHeader @eth.  Note that every
+ * returned ETableCol in the array has been referenced, to release
+ * this information you need to g_free the buffer returned
+ * and you need to gtk_object_unref every element returned
+ */
 ETableCol **
 e_table_header_get_columns (ETableHeader *eth)
 {
@@ -400,6 +458,12 @@ e_table_header_get_columns (ETableHeader *eth)
 	return ret;
 }
 
+/**
+ * e_table_header_selection_ok:
+ * eth: the ETableHeader to query.
+ *
+ * Seems deprecated.
+ */
 gboolean
 e_table_header_selection_ok (ETableHeader *eth)
 {
@@ -409,6 +473,12 @@ e_table_header_selection_ok (ETableHeader *eth)
 	return eth->selectable;
 }
 
+/**
+ * e_table_header_get_selected:
+ * @eth: The ETableHeader to query
+ *
+ * Returns: The number of selected columns in the @eth object.
+ */
 int
 e_table_header_get_selected (ETableHeader *eth)
 {
@@ -426,6 +496,13 @@ e_table_header_get_selected (ETableHeader *eth)
 	return selected;
 }
 
+/**
+ * e_table_header_total_width:
+ * @eth: The ETableHeader to query
+ *
+ * Returns: the number of pixels used by the @eth object
+ * when rendered on screen
+ */
 int
 e_table_header_total_width (ETableHeader *eth)
 {
@@ -441,17 +518,16 @@ e_table_header_total_width (ETableHeader *eth)
 	return total;
 }
 
-static void
-eth_do_remove (ETableHeader *eth, int idx, gboolean do_unref)
-{
-	if (do_unref)
-		gtk_object_unref (GTK_OBJECT (eth->columns [idx]));
-	
-	memmove (&eth->columns [idx], &eth->columns [idx+1],
-		 sizeof (ETableCol *) * (eth->col_count - idx - 1));
-	eth->col_count--;
-}
-
+/**
+ * e_table_header_move:
+ * @eth: The ETableHeader to operate on.
+ * @source_index: the source column to move.
+ * @target_index: the target location for the column
+ *
+ * This function moves the column @source_index to @target_index
+ * inside the @eth ETableHeader.  The signals "dimension_change"
+ * and "structure_change" will be emmited
+ */
 void
 e_table_header_move (ETableHeader *eth, int source_index, int target_index)
 {
@@ -476,6 +552,14 @@ e_table_header_move (ETableHeader *eth, int source_index, int target_index)
 	gtk_signal_emit (GTK_OBJECT (eth), eth_signals [STRUCTURE_CHANGE]);
 }
 
+/**
+ * e_table_header_remove:
+ * @eth: The ETableHeader to operate on.
+ * @idx: the index to the column to be removed.
+ *
+ * Removes the column at @idx position in the ETableHeader @eth.
+ * This emmits the "structure_change" signal on the @eth object.
+ */
 void
 e_table_header_remove (ETableHeader *eth, int idx)
 {
@@ -489,6 +573,9 @@ e_table_header_remove (ETableHeader *eth, int idx)
 	gtk_signal_emit (GTK_OBJECT (eth), eth_signals [STRUCTURE_CHANGE]);
 }
 
+/*
+ * FIXME: deprecated?
+ */
 void
 e_table_header_set_selection (ETableHeader *eth, gboolean allow_selection)
 {
@@ -496,15 +583,6 @@ e_table_header_set_selection (ETableHeader *eth, gboolean allow_selection)
 	g_return_if_fail (E_IS_TABLE_HEADER (eth));
 }
 
-void
-e_table_header_set_size(ETableHeader *eth, int idx, int size)
-{
-	g_return_if_fail (eth != NULL);
-	g_return_if_fail (E_IS_TABLE_HEADER (eth));
-
-	enqueue(eth, idx, size);
-}
-
 static void
 eth_set_size (ETableHeader *eth, int idx, int size)
 {
@@ -624,6 +702,18 @@ eth_set_size (ETableHeader *eth, int idx, int size)
 	}
 }
 
+/**
+ * e_table_header_col_diff:
+ * @eth: the ETableHeader to query.
+ * @start_col: the starting column
+ * @end_col: the ending column.
+ *
+ * Computes the number of pixels between the columns @start_col and
+ * @end_col.
+ *
+ * Returns: the number of pixels between @start_col and @end_col on the
+ * @eth ETableHeader object
+ */
 int
 e_table_header_col_diff (ETableHeader *eth, int start_col, int end_col)
 {
@@ -679,3 +769,27 @@ eth_calc_widths (ETableHeader *eth)
 	eth_update_offsets (eth);
 	gtk_signal_emit (GTK_OBJECT (eth), eth_signals [DIMENSION_CHANGE]);
 }
+
+GtkType
+e_table_header_get_type (void)
+{
+	static GtkType type = 0;
+
+	if (!type){
+		GtkTypeInfo info = {
+			"ETableHeader",
+			sizeof (ETableHeader),
+			sizeof (ETableHeaderClass),
+			(GtkClassInitFunc) e_table_header_class_init,
+			(GtkObjectInitFunc) e_table_header_init,
+			NULL, /* reserved 1 */
+			NULL, /* reserved 2 */
+			(GtkClassInitFunc) NULL
+		};
+
+		type = gtk_type_unique (gtk_object_get_type (), &info);
+	}
+
+	return type;
+}
+
diff --git a/widgets/table/e-table-model.c b/widgets/table/e-table-model.c
index 5138fb8edd..566d28d084 100644
--- a/widgets/table/e-table-model.c
+++ b/widgets/table/e-table-model.c
@@ -2,10 +2,11 @@
 /*
  * e-table-model.c: a Table Model
  *
- * Author:
+ * Authors:
  *   Miguel de Icaza (miguel@gnu.org)
+ *   Chris Lahey (clahey@helixcode.com)
  *
- * (C) 1999 Helix Code, Inc.
+ * (C) 1999, 2000 Helix Code, Inc.
  */
 #include <config.h>
 #include <gtk/gtksignal.h>
@@ -35,6 +36,12 @@ enum {
 
 static guint e_table_model_signals [LAST_SIGNAL] = { 0, };
 
+/**
+ * e_table_model_column_count:
+ * @e_table_model: The e-table-model to operate on
+ *
+ * Returns: the number of columns in the table model.
+ */
 int
 e_table_model_column_count (ETableModel *e_table_model)
 {
@@ -45,6 +52,12 @@ e_table_model_column_count (ETableModel *e_table_model)
 }
 
 
+/**
+ * e_table_model_row_count:
+ * @e_table_model: the e-table-model to operate on
+ *
+ * Returns: the number of rows in the Table model.
+ */
 int
 e_table_model_row_count (ETableModel *e_table_model)
 {
@@ -54,6 +67,19 @@ e_table_model_row_count (ETableModel *e_table_model)
 	return ETM_CLASS (e_table_model)->row_count (e_table_model);
 }
 
+/**
+ * e_table_value_at:
+ * @e_table_model: the e-table-model to operate on
+ * @col: column in the model to pull data from.
+ * @row: row in the model to pull data from.
+ *
+ * Return value: This function returns the value that is stored
+ * by the @e_table_model in column @col and row @row.  The data
+ * returned can be a pointer or any data value that can be stored
+ * inside a pointer.
+ *
+ * The data returned is typically used by an ECell renderer
+ */
 void *
 e_table_model_value_at (ETableModel *e_table_model, int col, int row)
 {
@@ -63,6 +89,21 @@ e_table_model_value_at (ETableModel *e_table_model, int col, int row)
 	return ETM_CLASS (e_table_model)->value_at (e_table_model, col, row);
 }
 
+/**
+ * e_table_model_set_value_at:
+ * @e_table_model: the table model to operate on.
+ * @col: the column where the data will be stored in the model.
+ * @row: the row where the data will be stored in the model. 
+ * @data: the data to be stored.
+ *
+ * This function instructs the model to store the value in @data in the
+ * the @e_table_model at column @col and row @row.  The @data typically
+ * comes from one of the ECell rendering objects.
+ *
+ * There should be an agreement between the Table Model and the user
+ * of this function about the data being stored.  Typically it will
+ * be a pointer to a set of data, or a datum that fits inside a void *.
+ */
 void
 e_table_model_set_value_at (ETableModel *e_table_model, int col, int row, const void *data)
 {
@@ -72,6 +113,15 @@ e_table_model_set_value_at (ETableModel *e_table_model, int col, int row, const
 	ETM_CLASS (e_table_model)->set_value_at (e_table_model, col, row, data);
 }
 
+/**
+ * e_table_model_is_cell_editable:
+ * @e_table_model: the table model to query.
+ * @col: column to query.
+ * @row: row to query.
+ *
+ * Returns: %TRUE if the cell in @e_table_model at @col,@row can be
+ * edited, %FALSE otherwise
+ */
 gboolean
 e_table_model_is_cell_editable (ETableModel *e_table_model, int col, int row)
 {
@@ -81,6 +131,13 @@ e_table_model_is_cell_editable (ETableModel *e_table_model, int col, int row)
 	return ETM_CLASS (e_table_model)->is_cell_editable (e_table_model, col, row);
 }
 
+/**
+ * e_table_model_append_row:
+ * @e_table_model: the table model to append the a row to.
+ * @source:
+ * @row:
+ *
+ */
 void
 e_table_model_append_row (ETableModel *e_table_model, ETableModel *source, int row)
 {
@@ -264,24 +321,24 @@ e_table_model_class_init (GtkObjectClass *object_class)
 guint
 e_table_model_get_type (void)
 {
-  static guint type = 0;
-
-  if (!type)
-    {
-      GtkTypeInfo info =
-      {
-	"ETableModel",
-	sizeof (ETableModel),
-	sizeof (ETableModelClass),
-	(GtkClassInitFunc) e_table_model_class_init,
-	NULL,
-	/* reserved_1 */ NULL,
-        /* reserved_2 */ NULL,
-        (GtkClassInitFunc) NULL,
-      };
-
-      type = gtk_type_unique (PARENT_TYPE, &info);
-    }
+	static guint type = 0;
+	
+	if (!type)
+	{
+		GtkTypeInfo info =
+		{
+			"ETableModel",
+			sizeof (ETableModel),
+			sizeof (ETableModelClass),
+			(GtkClassInitFunc) e_table_model_class_init,
+			NULL,
+			/* reserved_1 */ NULL,
+			/* reserved_2 */ NULL,
+			(GtkClassInitFunc) NULL,
+		};
+		
+		type = gtk_type_unique (PARENT_TYPE, &info);
+	}
 
   return type;
 }
@@ -310,6 +367,19 @@ e_table_model_pre_change (ETableModel *e_table_model)
 	d(depth--);
 }
 
+/**
+ * e_table_model_changed:
+ * @e_table_model: the table model to notify of the change
+ *
+ * Use this function to notify any views of this table model that
+ * the contents of the table model have changed.  This will emit
+ * the signal "model_changed" on the @e_table_model object.
+ *
+ * It is preferable to use the e_table_model_row_changed() and
+ * the e_table_model_cell_changed() to notify of smaller changes
+ * than to invalidate the entire model, as the views might have
+ * ways of caching the information they render from the model.
+ */
 void
 e_table_model_changed (ETableModel *e_table_model)
 {
@@ -324,6 +394,16 @@ e_table_model_changed (ETableModel *e_table_model)
 	d(depth--);
 }
 
+/**
+ * e_table_model_row_changed:
+ * @e_table_model: the table model to notify of the change
+ * @row: the row that was changed in the model.
+ *
+ * Use this function to notify any views of the table model that
+ * the contents of row @row have changed in model.  This function
+ * will emit the "model_row_changed" signal on the @e_table_model
+ * object
+ */
 void
 e_table_model_row_changed (ETableModel *e_table_model, int row)
 {
@@ -338,6 +418,17 @@ e_table_model_row_changed (ETableModel *e_table_model, int row)
 	d(depth--);
 }
 
+/**
+ * e_table_model_cell_changed:
+ * @e_table_model: the table model to notify of the change
+ * @col: the column.
+ * @row: the row
+ *
+ * Use this function to notify any views of the table model that
+ * contents of the cell at @col,@row has changed. This will emit
+ * the "model_cell_changed" signal on the @e_table_model
+ * object
+ */
 void
 e_table_model_cell_changed (ETableModel *e_table_model, int col, int row)
 {
@@ -352,6 +443,16 @@ e_table_model_cell_changed (ETableModel *e_table_model, int col, int row)
 	d(depth--);
 }
 
+/**
+ * e_table_model_row_inserted:
+ * @e_table_model: the table model to notify of the change
+ * @row: the row that was inserted into the model.
+ *
+ * Use this function to notify any views of the table model that
+ * the row @row has been inserted into the model.  This function
+ * will emit the "model_row_inserted" signal on the @e_table_model
+ * object
+ */
 void
 e_table_model_row_inserted (ETableModel *e_table_model, int row)
 {
@@ -366,6 +467,16 @@ e_table_model_row_inserted (ETableModel *e_table_model, int row)
 	d(depth--);
 }
 
+/**
+ * e_table_model_row_deleted:
+ * @e_table_model: the table model to notify of the change
+ * @row: the row that was deleted
+ *
+ * Use this function to notify any views of the table model that
+ * the row @row has been deleted from the model.  This function
+ * will emit the "model_row_deleted" signal on the @e_table_model
+ * object
+ */
 void
 e_table_model_row_deleted (ETableModel *e_table_model, int row)
 {