ActionMap: Improve add_action_with_parameter docs

 • Clarify why the old overload has been deprecated: it simply does not
   work for the desired result because the parameter_type was not passed

 • Elaborate on the purpose of the parameter_type in the new overload.

https://bugzilla.gnome.org/show_bug.cgi?id=774444

1 files changed, 6 insertions, 4 deletions

diff --git a/gio/src/actionmap.hg b/gio/src/actionmap.hg
index 4d3a1f70..4194cdb3 100644
--- a/gio/src/actionmap.hg
+++ b/gio/src/actionmap.hg
@@ -101,16 +101,18 @@ _DEPRECATE_IFDEF_START
    *
    * @param name The name of the Action.
    * @param slot The callback method to be called when the action is activated.
-   * @parameter_type The type of parameter to be passed to the slot.
    * @return The Action.
    *
-   * @deprecated Use the add_action_with_parameter() override that takes the parameter_type.
+   * @deprecated This overload does not work as it does not set a parameter
+   * type on the Action, so activating it with a parameter cannot work. Use the
+   * other add_action_with_parameter() overload, which takes a parameter type.
    */
   Glib::RefPtr<SimpleAction> add_action_with_parameter(const Glib::ustring& name, const ActivateWithParameterSlot& slot);
 _DEPRECATE_IFDEF_END
 
-  /** A convenience method for creating a SimpleAction instance
-   * and adding it to the ActionMap.
+  /** A convenience method for creating a SimpleAction instance, which when
+   * activated will call a slot receiving a given type of parameter, and adding
+   * that SimpleAction to the ActionMap.
    *
    * @param name The name of the Action.
    * @param parameter_type The type of parameter to be passed to the slot.