From fbf99febf3c686565a44f11553007d3d7eec68f2 Mon Sep 17 00:00:00 2001
From: Benjamin Otte <otte@redhat.com>
Date: Thu, 20 Mar 2014 14:34:31 +0100
Subject: [PATCH] docs: Add more information to gtk_widget_set_realized()

It's important to point out that widgets should only be marked as
realized very late in the process. Even GTK widgets don't get this
right.

https://bugzilla.gnome.org/show_bug.cgi?id=726717
---
 gtk/gtkwidget.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 9541e596e2..b82819a852 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8609,7 +8609,9 @@ gtk_widget_get_realized (GtkWidget *widget)
  * @widget: a #GtkWidget
  * @realized: %TRUE to mark the widget as realized
  *
- * Marks the widget as being realized.
+ * Marks the widget as being realized. This function must only be 
+ * called after all #GdkWindows for the @widget have been created 
+ * and registered.
  *
  * This function should only ever be called in a derived widget's
  * “realize” or “unrealize” implementation.