[gtk+] GtkComboBox(Text): Add documentation about the entry

[Matthias Clasen <matthiasc src gnome org>]

commit 52e1722f35a970538d9c9fdcd94948792cb21245
Author: Milan Bouchet-Valat <nalimilan club fr>
Date:   Mon Dec 13 21:45:07 2010 +0100

    GtkComboBox(Text): Add documentation about the entry

 gtk/gtkcombobox.c     |    7 ++++++-
 gtk/gtkcomboboxtext.c |   10 ++++++++--
 2 files changed, 14 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 648b534..d4a90ec 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -77,9 +77,14 @@
  * not restricted to a flat list, it can be a real tree, and the popup will
  * reflect the tree structure.
  *
+ * To allow the user to enter values not in the model, the 'has-entry'
+ * property allows the GtkComboBox to contain a #GtkEntry. This entry
+ * can be accessed by calling gtk_bin_get_child() on the combo box.
+ *
  * For a simple list of textual choices, the model-view API of GtkComboBox
  * can be a bit overwhelming. In this case, #GtkComboBoxText offers a
- * simple alternative.
+ * simple alternative. Both GtkComboBox and #GtkComboBoxText can contain
+ * an entry.
  */
 
 
diff --git a/gtk/gtkcomboboxtext.c b/gtk/gtkcomboboxtext.c
index 4e67c6c..a9a09a2 100644
--- a/gtk/gtkcomboboxtext.c
+++ b/gtk/gtkcomboboxtext.c
@@ -39,6 +39,11 @@
  * gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text()
  * or gtk_combo_box_text_prepend_text() and remove options with
  * gtk_combo_box_text_remove().
+ *
+ * If the GtkComboBoxText contains an entry (via the 'has-entry' property),
+ * its contents can be retrieved using gtk_combo_box_text_get_active_text().
+ * The entry itself can be accessed by calling gtk_bin_get_child() on the
+ * combo box.
  */
 
 G_DEFINE_TYPE (GtkComboBoxText, gtk_combo_box_text, GTK_TYPE_COMBO_BOX);
@@ -336,8 +341,9 @@ gtk_combo_box_text_remove_all (GtkComboBoxText *combo_box)
  * gtk_combo_box_text_get_active_text:
  * @combo_box: A #GtkComboBoxText
  *
- * Returns the currently active string in @combo_box or %NULL if none
- * is selected.
+ * Returns the currently active string in @combo_box, or %NULL if none
+ * is selected. If @combo_box contains an entry, this function will return
+ * its contents (which will not necessarily be an item from the list).
  *
  * Returns: a newly allocated string containing the currently active text.
  *     Must be freed with g_free().