[glib] GActionEntry: improve documentation

[Ryan Lortie <desrt src gnome org>]

commit c78037773b574b6f15915c23299eb7a2ff3c1900
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 |   12 +++++++++---
 1 files changed, 9 insertions(+), 3 deletions(-)
---
diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index cc4fdfe..bee2a81 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().