[glib/glib-2-40] GActionEntry: improve documentation

[Ryan Lortie <desrt src gnome org>]

commit 73bd87faa1affce3aafb189817ea93df7f2cbaa1
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Jun 29 11:13:25 2014 -0400

    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 |   19 +++++++++++++------
 1 files changed, 13 insertions(+), 6 deletions(-)
---
diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index cc4fdfe..c5b3d2e 100644
--- a/gio/gactionmap.c
+++ b/gio/gactionmap.c
@@ -124,16 +124,23 @@ 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.
+ * @state: the initial state for this action, given in
+ *         [GVariant text format][gvariant-text].  The state is parsed
+ *         with no extra type information, so type tags must be added to
+ *         the string if they are 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().