Improve the hildon_touch_selector_append_column() documentation

* hildon/hildon-touch-selector.c: Improve the documentation for
hildon_touch_selector_append_column().

Fixes MB#4641 (Documentation:
hildon_touch_selector_append_column() ref-counting)

diff --git a/ChangeLog b/ChangeLog
index 939373a..f951ad1 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2009-06-09  Claudio Saavedra  <csaavedra@igalia.com>
+
+       * hildon/hildon-touch-selector.c: Improve the documentation for
+       hildon_touch_selector_append_column().
+
+       Fixes MB#4641 (Documentation:
+       hildon_touch_selector_append_column() ref-counting)
+
 2009-06-08  Claudio Saavedra  <csaavedra@igalia.com>
 
        * tests/check-hildon-controlbar.c: (test_set_range_invalid):

diff --git a/hildon/hildon-touch-selector.c b/hildon/hildon-touch-selector.c
index d727f54..e769292 100644 (file)
--- a/hildon/hildon-touch-selector.c
+++ b/hildon/hildon-touch-selector.c
@@ -1158,22 +1158,24 @@ hildon_touch_selector_insert_text (HildonTouchSelector * selector,
  *
  * This functions adds a new column to the widget, whose data will
  * be obtained from the model. Only widgets added this way should used on
- * the selection logic, i.e., the print function, the #HildonTouchPicker::changed
- * signal, etc.
+ * the selection logic, the print function, the #HildonTouchSelector::changed
+ * signal, etc. Internally, a #GtkTreeView will be added to the widget, using
+ * @model as the data source.
  *
  * You can optionally pass a #GtkCellRenderer in @cell_renderer,
  * together with a %NULL-terminated list of pairs property/value, in
  * the same way you would use gtk_tree_view_column_set_attributes().
- * This will pack @cell_renderer at the start of the column, expanded by default.
- * If you prefer not to add it this way, you can simply pass %NULL to @cell_renderer
- * and use the #GtkCellLayout interface on the returned #HildonTouchSelectorColumn
- * to set your renderers.
- *
- * There is a prerequisite to be considered on models used: text data must
- * be in the first column.
- *
- * This method basically adds a #GtkTreeView to the widget, using the model and
- * the data received.
+ * This will pack @cell_renderer at the start of the column, expanded
+ * by default.  If you prefer not to add it this way, you can simply
+ * pass %NULL to @cell_renderer and use the #GtkCellLayout interface
+ * on the returned #HildonTouchSelectorColumn to set your
+ * renderers. Please note that the returned #HildonTouchSelectorColumn
+ * is owned by @selector, you shouldn't unref it after setting it
+ * up.
+ *
+ * Initially, the returned #HildonTouchSelectorColumn will have its
+ * #HildonTouchSelectorColumn:text-column property unset. You should set
+ * it to a column in @model with type %G_TYPE_STRING.
  *
  * Returns: the new column added added, %NULL otherwise.
  *