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

@@ -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.