diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 27f5184018..7961dc9fca 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -81,7 +81,11 @@
  *
  * The main properties of a GtkSpinButton are through an adjustment.
  * See the #GtkAdjustment section for more details about an adjustment's
- * properties.
+ * properties. Note that GtkSpinButton will by default make its entry
+ * large enough to accomodate the lower and upper bounds of the adjustment,
+ * which can lead to surprising results. Best practice is to set both
+ * the #GtkEntry::width-chars and #GtkEntry::max-width-chars poperties
+ * to the desired number of characters to display in the entry.
  *
  * # CSS nodes
  *