diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index a6191bd0d1..03a16aac49 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -201,6 +201,19 @@ gtk_style_context_class_init (GtkStyleContextClass *klass)
 
   klass->changed = gtk_style_context_real_changed;
 
+  /**
+   * GtkStyleContext::changed:
+   *
+   * The ::changed signal is emitted when there is a change in the
+   * #GtkStyleContext.
+   *
+   * For a #GtkStyleContext returned by gtk_widget_get_style_context(), the
+   * #GtkWidget::style-updated signal/vfunc might be more convenient to use.
+   *
+   * This signal is useful when using the theming layer standalone.
+   *
+   * Since: 3.0
+   */
   signals[CHANGED] =
     g_signal_new (I_("changed"),
                   G_TYPE_FROM_CLASS (object_class),
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 52a9995741..cf9e4c69fc 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1903,9 +1903,12 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * GtkWidget::style-updated:
    * @widget: the object on which the signal is emitted
    *
-   * The ::style-updated signal is emitted when the #GtkStyleContext
-   * of a widget is changed. Note that style-modifying functions like
-   * gtk_widget_override_color() also cause this signal to be emitted.
+   * The ::style-updated signal is a convenience signal that is emitted when the
+   * #GtkStyleContext::changed signal is emitted on the @widget's associated
+   * #GtkStyleContext as returned by gtk_widget_get_style_context().
+   *
+   * Note that style-modifying functions like gtk_widget_override_color() also
+   * cause this signal to be emitted.
    *
    * Since: 3.0
    */