[glibmm] Docs: Add Action* and MenuItem docs.

[Murray Cumming <murrayc src gnome org>]

commit 3aec72e2642f9daad798fb0206308b119b2a9684
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Oct 8 09:38:10 2013 +0200

    Docs: Add Action* and MenuItem docs.

 gio/src/action.hg       |   53 +++++++++++++++++++++++++++++++++++++++++++---
 gio/src/actiongroup.hg  |   33 +++++++++++++++++++++++++++-
 gio/src/actionmap.hg    |    3 +-
 gio/src/menuitem.hg     |   30 ++++++++++++++++++++++++--
 gio/src/simpleaction.hg |   19 +++++++++++++++-
 5 files changed, 125 insertions(+), 13 deletions(-)
---
diff --git a/gio/src/action.hg b/gio/src/action.hg
index 3e26652..f5c4a68 100644
--- a/gio/src/action.hg
+++ b/gio/src/action.hg
@@ -79,9 +79,26 @@ public:
   _WRAP_METHOD(Glib::VariantType get_parameter_type() const, g_action_get_parameter_type)
   _WRAP_METHOD(Glib::VariantType get_state_type() const, g_action_get_state_type)
 
-  //TODO: Docs
   //TODO: Is there any specific type that can really be used with this? A std::list<>. We must test this.
   //  See also ActionGroup:::get_action_state_hint().
+  /** Requests a hint about the valid range of values for the state of
+   * the action.
+   *
+   * If a null Variant is returned it either means that the action is not stateful
+   * or that there is no hint about the valid range of values for the
+   * state of the action.
+   *
+   * If a Variant array is returned then each item in the array is a
+   * possible value for the state.  If a Variant pair (ie: two-tuple) is
+   * returned then the tuple specifies the inclusive lower and upper bound
+   * of valid values for the state.
+   *
+   * In any case, the information is merely a hint.  It may be possible to
+   * have a state value outside of the hinted range and setting a value
+   * within the range may fail.
+   *
+   * @param value This will be set to the state range hint.
+   */
   template <typename T_Value>
   void get_state_hint(T_Value& value) const;
 
@@ -118,13 +135,26 @@ public:
 
   _WRAP_METHOD(void change_state(const Glib::VariantBase& value), g_action_change_state, deprecated "Use the 
templated method instead, passing a normal C++ type.")
 
-  //TODO: Docs
+  /** Queries the current state of the action.
+   *
+   * If the action is not stateful then a null Variant will be returned.  If the
+   * action is stateful then the type of the return value is the type
+   * given by get_state_type().
+   *
+   * @param value This will be set to the current state of the action.
+   */
   template <typename T_Value>
   void get_state(T_Value& value) const;
 
   _WRAP_METHOD(Glib::VariantBase get_state_variant() const, g_action_get_state)
 
-  //TODO: Docs
+  /** Activates the action.
+   *
+   * The @a parameter must be the correct type of parameter for the action (ie:
+   * the parameter type given at construction time), if any.
+   *
+   * @param parameter: The parameter to the activation
+   */
   template <typename T_Value>
   void activate(const T_Value& parameter);
 
@@ -143,7 +173,22 @@ public:
 
   //TODO: _WRAP_METHOD(static bool parse_detailed_name(const Glib::ustring& detailed_name, gchar** 
action_name, GVariant** target_value), g_action_parse_detailed_name, errthrow)
 
-  //TODO: Docs.
+
+  /** Formats a detailed action name from @a action_name and @a target_value.
+   *
+   * It is an error to call this function with an invalid action name.
+   *
+   * This function is the opposite of parse_detailed_action_name(). 
+   * It will produce a string that can be parsed back to the @a action_name
+   * and @a target_value by that function.
+   *
+   * See that function for the types of strings that will be printed by
+   * this function.
+   *
+   * @param action_name A valid action name.
+   * @param target_value A Variant target value.
+   * @result A detailed format string.
+   */
   template <typename T_Value>
   Glib::ustring print_detailed_name(const Glib::ustring& action_name, const T_Value& value);
 
diff --git a/gio/src/actiongroup.hg b/gio/src/actiongroup.hg
index a715eea..2edafaa 100644
--- a/gio/src/actiongroup.hg
+++ b/gio/src/actiongroup.hg
@@ -78,7 +78,27 @@ public:
 
   _WRAP_METHOD(Glib::VariantContainerBase get_action_state_hint(const Glib::ustring& action_name) const, 
g_action_group_get_action_state_hint, deprecated "Use the get_action_state() method that takes an output 
parameter instead.")
 
-  //TODO: Docs
+  //TODO: How do we check for a NULL Variant?
+  /**
+   * Requests a hint about the valid range of values for the state of the
+   * named action within the action group
+   *
+   * If a null Variant is returned it either means that the action is not stateful
+   * or that there is no hint about the valid range of values for the
+   * state of the action.
+   *
+   * If a ariant array is returned then each item in the array is a
+   * possible value for the state.  If Variant pair (ie: two-tuple) is
+   * returned then the tuple specifies the inclusive lower and upper bound
+   * of valid values for the state.
+   *
+   * In any case, the information is merely a hint.  It may be possible to
+   * have a state value outside of the hinted range and setting a value
+   * within the range may fail.
+   *
+   * @param action_name The name of the action to query.
+   * @param value This will be set to the state range hint.
+   */
   template <typename T_Value>
   void get_action_state_hint(const Glib::ustring& action_name, T_Value& value) const;
 
@@ -87,7 +107,16 @@ public:
 
   _WRAP_METHOD(Glib::VariantBase get_action_state(const Glib::ustring& action_name) const, 
g_action_group_get_action_state, deprecated "Use the get_action_state() method that takes an output parameter 
instead.")
 
-  //TODO: Docs
+  //TODO: How do we check for a NULL Variant?
+  /** Queries the current state of the named action within the action group.
+   *
+   * If the action is not stateful then a null Variant will be returned.  If the
+   * action is stateful then the type of the return value is the type
+   * given by get_action_state_type().
+   *
+   * @param action_name The name of the action to query.
+   * @param value This will be set to the current state of the action.
+   */
   template <typename T_Value>
   void get_action_state(const Glib::ustring& action_name, T_Value& value) const;
 
diff --git a/gio/src/actionmap.hg b/gio/src/actionmap.hg
index 97cf32a..4400a68 100644
--- a/gio/src/actionmap.hg
+++ b/gio/src/actionmap.hg
@@ -112,8 +112,7 @@ public:
    */
   Glib::RefPtr<SimpleAction> add_action_bool(const Glib::ustring& name, bool state = false);
 
-//TODO: Docs: Refer to this as a toggle action?
-  /** A convenience method for creating a boolean-stateful SimpleAction instance
+  /** A convenience method for creating a boolean-stateful (toggle) SimpleAction instance
    * and adding it to the ActionMap.
    *
    * @param name The name of the Action.
diff --git a/gio/src/menuitem.hg b/gio/src/menuitem.hg
index dae752b..e7eb6c3 100644
--- a/gio/src/menuitem.hg
+++ b/gio/src/menuitem.hg
@@ -34,14 +34,38 @@ class MenuItem : public Glib::Object
   _CLASS_GOBJECT(MenuItem, GMenuItem, G_MENU_ITEM, Glib::Object, GObject)
 
 protected:
-  //TODO: Documentation
+  /** Creates a new MenuItem.
+   *
+   * If @a label is not empty it is used to set the "label" attribute of the
+   * new item.
+   *
+   * If @a detailed_action is not empty it is used to set the "action" and
+   * possibly the "target" attribute of the new item.  See
+   * set_detailed_action() for more information.
+   *
+   * @param label The section label.
+   * @param detailed_action: The detailed action string.
+   */
   explicit MenuItem(const Glib::ustring& label = Glib::ustring(), const Glib::ustring& detailed_action = 
Glib::ustring());
   _IGNORE(g_menu_item_new)
 
-  //TODO: Documentation
+  /** Creates a new MenuItem representing a submenu.
+   *
+   * This is a convenience API around the MenuItem(label, detailed_action) constructor and
+   * set_submenu().
+   *
+   * @param label The section label.
+   * @param A MenuModel with the items of the submenu.
+   */
   explicit MenuItem(const Glib::ustring& label, const Glib::RefPtr<MenuModel>& submenu);
 
-  //TODO: Documentation
+  /** Creates a new MenuItem representing a submenu.
+   *
+   * This is a convenience API around the MenuItem(label, detailed_action) constructor and
+   * set_submenu().
+   *
+   * @param A MenuModel with the items of the submenu.
+   */
   explicit MenuItem(const Glib::RefPtr<MenuModel>& submenu);
   _IGNORE(g_menu_item_new_submenu)
 
diff --git a/gio/src/simpleaction.hg b/gio/src/simpleaction.hg
index 20a240d..0a5059a 100644
--- a/gio/src/simpleaction.hg
+++ b/gio/src/simpleaction.hg
@@ -45,10 +45,25 @@ class SimpleAction : public Glib::Object, public Action
   _STRUCT_NOT_HIDDEN
 
 protected:
-  //TODO: Docs
+  /** Creates a new action.
+   *
+   * The created action is stateless.
+   *
+   * @param name The name of the action.
+   * @param state The initial state of the action.
+   */
   explicit SimpleAction(const Glib::ustring& name);
 
-  //TODO: Docs
+  /** Creates a new new stateful action.
+   *
+   * The created action is stateless.
+   *
+   * @a state is the initial state of the action.  All future state values
+   * must have the same VariantType as the initial state.
+   *
+   * @param name The name of the action.
+   * @param state The initial state of the action.
+   */
   SimpleAction(const Glib::ustring& name, const Glib::VariantBase& state);
 
 #m4 _CONVERSION(`const Glib::VariantType&',`const GVariantType*',`$3.gobj()')