From c78037773b574b6f15915c23299eb7a2ff3c1900 Mon Sep 17 00:00:00 2001
From: Ryan Lortie <desrt@desrt.ca>
Date: Sun, 29 Jun 2014 11:13:25 -0400
Subject: [PATCH] GActionEntry: improve documentation

Document that giving %NULL for the activate handler is supported since
GLib 2.40.  We documented this on GSimpleAction itself (where the
default handler functionality is implemented) but expecting the user to
dig that up is asking a bit much.

Also, add some more explicit documentation about the conditions under
which each field is expected to be filled in.

https://bugzilla.gnome.org/show_bug.cgi?id=732429
---
 gio/gactionmap.c | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

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().