diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c
index 0f26c0f74..bf8dd7373 100644
--- a/gio/gsimpleaction.c
+++ b/gio/gsimpleaction.c
@@ -351,6 +351,28 @@ g_simple_action_class_init (GSimpleActionClass *class)
    * default action is taken.  If the state should change then you must
    * call g_simple_action_set_state() from the handler.
    *
+   * <example>
+   * <title>Example 'change-state' handler</title>
+   * <programlisting>
+   * static void
+   * change_volume_state (GSimpleAction *action,
+   *                      GVariant      *value,
+   *                      gpointer       user_data)
+   * {
+   *   gint requested;
+   *
+   *   requested = g_variant_get_int32 (value);
+   *
+   *   // Volume only goes from 0 to 10
+   *   if (0 <= requested && requested <= 10)
+   *     g_simple_action_set_state (action, value);
+   * }
+   * </programlisting>
+   * </example>
+   *
+   * The handler need not set the state to the requested value.  It
+   * could set it to any value at all, or take some other action.
+   *
    * Since: 2.30
    */
   g_simple_action_signals[SIGNAL_CHANGE_STATE] =