[glibmm] Gio::Action: Add more documentation of get_state_hint() and get_state().

[Kjell Ahlstedt <kjellahl src gnome org>]

commit fea3c2189ad1398f1b69f03f3db4385322c61a8c
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Fri Dec 28 15:51:22 2012 +0100

    Gio::Action: Add more documentation of get_state_hint() and get_state().
    
    * gio/src/action.hg: get_state_hint() and get_state() returns void, which
    makes them useless. That can't be fixed until the next ABI break. Explain in
    the documentation what to do instead of calling these methods. Bug #690134.

 ChangeLog         |    8 ++++++
 gio/src/action.hg |   63 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4a41e0e..a33a7ea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2012-12-28  Kjell Ahlstedt  <kjell ahlstedt bredband net>
+
+	Gio::Action: Add more documentation of get_state_hint() and get_state().
+
+	* gio/src/action.hg: get_state_hint() and get_state() returns void, which
+	makes them useless. That can't be fixed until the next ABI break. Explain in
+	the documentation what to do instead of calling these methods. Bug #690134.
+
 2012-12-27  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	SignalProxy: Fix the documentation, especially of connect_notify().
diff --git a/gio/src/action.hg b/gio/src/action.hg
index baa9b22..c14fa84 100644
--- a/gio/src/action.hg
+++ b/gio/src/action.hg
@@ -77,8 +77,71 @@ public:
   _WRAP_METHOD(Glib::ustring get_name() const, g_action_get_name)
   _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: Change the return type of get_state_hint() when we can break ABI.
+  // See https://bugzilla.gnome.org/show_bug.cgi?id=690134
+  /** Requests a hint about the valid range of values for the state of
+   *  @a action.
+   *
+   * @note
+   * This method is useless in its present form. It should return Glib::VariantBase,
+   * but it returns @c void. This bug cannot be fixed until the ABI of glibmm can be broken.
+   * Meanwhile you can use the C function in glib like so:
+   * @code
+   * Glib::VariantBase state_hint = Glib::wrap(g_action_get_state_hint(myAction.gobj()));
+   * @endcode
+   * If myAction is a const object:
+   * @code
+   * Glib::VariantBase state_hint = Glib::wrap(g_action_get_state_hint(const_cast<GAction*>(myAction.gobj())));
+   * @endcode
+   *
+   * If <tt>0</tt> 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.
+   * 
+   * @newin{2,28}
+   * @return The state range hint.
+   */
   _WRAP_METHOD(void get_state_hint() const, g_action_get_state_hint)
+
   _WRAP_METHOD(bool get_enabled() const, g_action_get_enabled)
+
+  //TODO: Change the return type of get_state() when we can break ABI.
+  // See https://bugzilla.gnome.org/show_bug.cgi?id=690134
+  /** Queries the current state of @a action.
+   *
+   * @note
+   * This method is useless in its present form. It should return Glib::VariantBase,
+   * but it returns @c void. This bug cannot be fixed until the ABI of glibmm can be broken.
+   * Meanwhile you can use property_state() like so:
+   * @code
+   * Glib::VariantBase state = myAction.property_state();
+   * @endcode
+   * You can also use the C function in glib like so:
+   * @code
+   * Glib::VariantBase state = Glib::wrap(g_action_get_state(myAction.gobj()));
+   * @endcode
+   * If myAction is a const object:
+   * @code
+   * Glib::VariantBase state = Glib::wrap(g_action_get_state(const_cast<GAction*>(myAction.gobj())));
+   * @endcode
+   *
+   * If the action is not stateful then <tt>0</tt> will be returned.  If the
+   * action is stateful then the type of the return value is the type
+   * given by get_state_type().
+   * 
+   * @newin{2,28}
+   * @return The current state of the action.
+   */
   _WRAP_METHOD(void get_state() const, g_action_get_state)
 
   _WRAP_METHOD(void change_state(const Glib::VariantBase& value), g_action_change_state)