[gtk+] Add a note about placeholder text use

[Matthias Clasen <matthiasc src gnome org>]

commit 22d046d7fe858d71d83f7198bab03c89dedafe98
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Sep 2 00:35:38 2011 -0400

    Add a note about placeholder text use
    
    Explain how this is really not such a great feature...

 gtk/gtkentry.c |   15 +++++++++++----
 1 files changed, 11 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 89d8f6f..4e2e926 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -992,7 +992,8 @@ gtk_entry_class_init (GtkEntryClass *class)
   /**
   * GtkEntry:placeholder-text:
   *
-  * The text that will be displayed in the #GtkEntry when it is empty and unfocused.
+  * The text that will be displayed in the #GtkEntry when it is empty
+  * and unfocused.
   *
   * Since: 3.2
   */
@@ -10344,9 +10345,15 @@ gtk_entry_progress_pulse (GtkEntry *entry)
  * @entry: a #GtkEntry
  * @text: a string to be displayed when @entry is empty an unfocused, or %NULL
  *
- * Sets text to be displayed in @entry when
- * it is empty and unfocused. This can be used to give a visual hint
- * of the expected contents of the #GtkEntry.
+ * Sets text to be displayed in @entry when it is empty and unfocused.
+ * This can be used to give a visual hint of the expected contents of
+ * the #GtkEntry.
+ *
+ * Note that since the placeholder text gets removed when the entry
+ * received focus, using this feature is a bit problematic if the entry
+ * is given the initial focus in a window. Sometimes this can be
+ * worked around by delaying the initial focus setting until the
+ * first key event arrives.
  *
  * Since: 3.2
  **/