diff --git a/ChangeLog b/ChangeLog
index a20f8a1068..50818a0fd1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2004-11-09  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkwindow-x11.c (gdk_window_get_geometry): Add
+	a hint about using gdk_drawable_get_size() instead.
+
 	* gtk/gtk.symbols: Add new symbols.
 
 	* gtk/gtkiconview.c (gtk_icon_view_scroll_to_item): Make
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index a20f8a1068..50818a0fd1 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,5 +1,8 @@
 2004-11-09  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkwindow-x11.c (gdk_window_get_geometry): Add
+	a hint about using gdk_drawable_get_size() instead.
+
 	* gtk/gtk.symbols: Add new symbols.
 
 	* gtk/gtkiconview.c (gtk_icon_view_scroll_to_item): Make
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index a20f8a1068..50818a0fd1 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,5 +1,8 @@
 2004-11-09  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkwindow-x11.c (gdk_window_get_geometry): Add
+	a hint about using gdk_drawable_get_size() instead.
+
 	* gtk/gtk.symbols: Add new symbols.
 
 	* gtk/gtkiconview.c (gtk_icon_view_scroll_to_item): Make
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index a20f8a1068..50818a0fd1 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,5 +1,8 @@
 2004-11-09  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkwindow-x11.c (gdk_window_get_geometry): Add
+	a hint about using gdk_drawable_get_size() instead.
+
 	* gtk/gtk.symbols: Add new symbols.
 
 	* gtk/gtkiconview.c (gtk_icon_view_scroll_to_item): Make
diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c
index d6dfda7dfe..f5da16fcc3 100644
--- a/gdk/x11/gdkwindow-x11.c
+++ b/gdk/x11/gdkwindow-x11.c
@@ -2899,6 +2899,14 @@ gdk_window_set_cursor (GdkWindow *window,
  * #GdkEventConfigure. gdk_window_get_position() in contrast gets the
  * position from the most recent configure event.
  * 
+ * <note>
+ * If @window is not a toplevel, it is <emphasis>much</emphasis> better 
+ * to call gdk_window_get_position() and gdk_drawable_get_size() instead, 
+ * because it avoids the roundtrip to the X server and because 
+ * gdk_drawable_get_size() supports the full 32-bit coordinate space,
+ * whereas gdk_window_get_geometry() is restricted to the 16-bit
+ * coordinates of X11.
+ *</note>
  **/
 void
 gdk_window_get_geometry (GdkWindow *window,