Add long descriptions.

3 files changed, 47 insertions, 2 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 16add41023..fd51e80cbd 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2004-12-02  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/tmpl/gtkcombobox.sgml: 
+	* gtk/tmpl/gtkcomboboxentry.sgml: Add long descriptions.
+
 2004-12-01  Matthias Clasen  <mclasen@redhat.com>
 
 	* gdk/tmpl/windows.sgml: Document all window types.  (#160149,
diff --git a/docs/reference/gtk/tmpl/gtkcombobox.sgml b/docs/reference/gtk/tmpl/gtkcombobox.sgml
index 7421d29b81..f4b6ce831c 100644
--- a/docs/reference/gtk/tmpl/gtkcombobox.sgml
+++ b/docs/reference/gtk/tmpl/gtkcombobox.sgml
@@ -6,12 +6,37 @@ A widget used to choose from a list of items
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+A #GtkComboBox is a widget that allows the user to choose from a
+list of valid choices.  The #GtkComboBox displays the selected 
+choice.  When activated, the #GtkComboBox displays a popup 
+which allows the user to make a new choice. The style in which 
+the selected value is displayed, and the style of the popup is
+determined by the current theme. It may be similar to a #GtkOptionMenu,
+or similar to a Windows-style combo box.
+</para>
 
+<para>
+Unlike its predecessors #GtkCombo and #GtkOptionMenu, the #GtkComboBox
+uses the model-view pattern; the list of valid choices is specified in the
+form of a tree model, and the display of the choices can be adapted to
+the data in the model by using cell renderers, as you would in a tree view.
+This is possible since #GtkComboBox implements the #GtkCellLayout interface.
+The tree model holding the valid choices is not restricted to a flat list,
+it can be a real tree, and the popup will reflect the tree structure.
 </para>
 
-<!-- ##### SECTION See_Also ##### -->
 <para>
+In addition to the model-view API, #GtkComboBox offers a simple API which 
+is suitable for text-only combo boxes, and hides the complexity of managing
+the data in a model. It consists of the functions gtk_combo_box_new_text(), 
+gtk_combo_box_append_text(), gtk_combo_box_insert_text(), 
+gtk_combo_box_prepend_text(), gtk_combo_box_remove_text() and 
+gtk_combo_box_get_active_text().
+</para>
 
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkComboBoxEntry, #GtkTreeModel, #GtkCellRenderer
 </para>
 
 <!-- ##### STRUCT GtkComboBox ##### -->
diff --git a/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml b/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml
index 42e637f2d8..af3fc4e604 100644
--- a/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml
+++ b/docs/reference/gtk/tmpl/gtkcomboboxentry.sgml
@@ -6,12 +6,27 @@ A text entry field with a dropdown list
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+A #GtkComboBoxEntry is a widget that allows the user to choose from a
+list of valid choices or enter a different value. It is very similar
+to a #GtkComboBox, but it displays the selected value in an entry to
+allow modifying it.
+</para>
 
+<para>
+In contrast to a #GtkComboBox, the underlying model of a #GtkComboBoxEntry 
+must always have a text column (see gtk_combo_box_entry_set_text_column()),
+and the entry will show the content of the text column in the selected row.
 </para>
 
-<!-- ##### SECTION See_Also ##### -->
 <para>
+The convenience API to construct simple text-only #GtkComboBox<!-- -->es can
+also be used with #GtkComboBoxEntry<!-- -->s which have been constructed
+with gtk_combo_box_entry_new_text().
+</para>
 
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkComboBox
 </para>
 
 <!-- ##### STRUCT GtkComboBoxEntry ##### -->