diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index cc4fdfea9..bee2a8143 100644
--- a/gio/gactionmap.c
+++ b/gio/gactionmap.c
@@ -124,16 +124,22 @@ g_action_map_remove_action (GActionMap  *action_map,
  * GActionEntry:
  * @name: the name of the action
  * @activate: the callback to connect to the "activate" signal of the
- *            action
+ *            action.  Since GLib 2.40, this can be %NULL for stateful
+ *            actions, in which case the default handler is used.  For
+ *            boolean-stated actions with no parameter, this is a
+ *            toggle.  For other state types (and parameter type equal
+ *            to the state type) this will be a function that
+ *            just calls @change_state (which you should provide).
  * @parameter_type: the type of the parameter that must be passed to the
  *                  activate function for this action, given as a single
  *                  GVariant type string (or %NULL for no parameter)
  * @state: the initial state for this action, given in GVariant text
  *         format.  The state is parsed with no extra type information,
  *         so type tags must be added to the string if they are
- *         necessary.
+ *         necessary.  Stateless actions should give %NULL here.
  * @change_state: the callback to connect to the "change-state" signal
- *                of the action
+ *                of the action.  All stateful actions should provide a
+ *                handler here; stateless actions should not.
  *
  * This struct defines a single action.  It is for use with
  * g_action_map_add_action_entries().