diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index 311476fbf5..7295b1ff44 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -492,6 +492,33 @@
* url("gradient1.png") 10 10 10 10 stretch
*
*
+ *
+ * Styles can specify transitions that will be used to create a gradual
+ * change in the appearance when a widget state changes. The following
+ * syntax is used to specify transitions:
+ * @duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?
+ * The @duration is the amount of time that the animation will take for
+ * a complete cycle from start to end. If the loop option is given, the
+ * animation will be repated until the state changes again.
+ * The option after the duration determines the transition function from a
+ * small set of predefined functions.
+ * Linear transition
+ *
+ *
+ * Ease transition
+ *
+ *
+ * Ease-in-out transition
+ *
+ *
+ * Ease-in transition
+ *
+ *
+ * Ease-out transition
+ *
+ *
+ *
+ *
*
* Supported properties
*
@@ -612,7 +639,7 @@
*
*
* transition
- * duration [s|ms] [linear|ease|ease-in|ease-out|ease-in-out] [loop]?
+ * transition (see above)
*
* transition: 150ms ease-in-out;
* transition: 1s linear loop;
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index e4ad6125fb..7081e18e0a 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -66,6 +66,8 @@
* Transition animations
*
* #GtkStyleContext has built-in support for state change transitions.
+ * Note that these animations respect the #GtkSettings:gtk-enable-animations
+ * setting.
*
*
* For simple widgets where state changes affect the whole widget area,
@@ -164,25 +166,7 @@
* by the animation.
*
*
- * Transition animations can use several pre-defined transition functions:
- * Linear transition
- *
- *
- * Ease transition
- *
- *
- * Ease-in-out transition
- *
- *
- * Ease-in transition
- *
- *
- * Ease-out transition
- *
- *
- *
*
- *
*
* Custom styling in UI libraries and applications
*
@@ -2487,7 +2471,8 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
* @region_id: (allow-none): animatable region to notify on, or %NULL.
* See gtk_style_context_push_animatable_region()
* @state: state to trigger transition for
- * @state_value: target value of @state
+ * @state_value: %TRUE if @state is the state we are changing to, %FALSE if
+ * we are changing away from it
*
* Notifies a state change on @context, so if the current style makes use
* of transition animations, one will be started so all rendered elements
@@ -2527,6 +2512,9 @@ gtk_style_context_lookup_color (GtkStyleContext *context,
* if a pointer enters the button, and back to red if the pointer leaves
* the button.
*
+ * Note that @state is used when finding the transition parameters, which
+ * is why the style places the transition under the :hover pseudo-class.
+ *
* Since: 3.0
**/
void