diff --git a/gtk/deprecated/gtkstock.c b/gtk/deprecated/gtkstock.c
index 137fe68afa..2bdb4f9aed 100644
--- a/gtk/deprecated/gtkstock.c
+++ b/gtk/deprecated/gtkstock.c
@@ -36,10 +36,14 @@
 
 /**
  * SECTION:gtkstock
- * @Short_description:
-Prebuilt common menu/toolbar items and corresponding icons
+ * @Short_description: Prebuilt common menu/toolbar items and corresponding
+ *                     icons
  * @Title: Stock Items
  *
+ * > Since GTK+ 3.10, stock items are deprecated. You should instead set
+ * > up whatever labels and/or icons you need using normal widget API,
+ * > rather than relying on GTK+ providing ready-made combinations of these.
+ *
  * Stock items represent commonly-used menu or toolbar items such as
  * “Open” or “Exit”. Each stock item is identified by a stock ID;
  * stock IDs are just strings, but macros such as #GTK_STOCK_OPEN are
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 90e1a5d34a..26b7ffba38 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -1452,7 +1452,8 @@ gtk_button_new_from_icon_name (const gchar *icon_name,
  * gtk_button_new_from_stock:
  * @stock_id: the name of the stock item 
  *
- * Creates a new #GtkButton containing the image and text from a stock item.
+ * Creates a new #GtkButton containing the image and text from a
+ * [stock item][gtkstock].
  * Some stock ids have preprocessor macros like #GTK_STOCK_OK and
  * #GTK_STOCK_APPLY.
  *
@@ -1461,7 +1462,8 @@ gtk_button_new_from_icon_name (const gchar *icon_name,
  *
  * Returns: a new #GtkButton
  *
- * Deprecated: 3.10: Use gtk_button_new_with_label() instead.
+ * Deprecated: 3.10: Stock items are deprecated. Use gtk_button_new_with_label()
+ * instead.
  */
 GtkWidget*
 gtk_button_new_from_stock (const gchar *stock_id)