[gtk/ebassi/activate-signal] docs: Clarify gtk_widget_activate()

[Emmanuele Bassi <ebassi src gnome org>]

commit d8c9a67d2027631160477fa16a0f5bc839fabd9c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Dec 6 15:13:57 2020 +0000

    docs: Clarify gtk_widget_activate()
    
    We need to tell people what signal will be emitted when calling
    gtk_widget_activate(), and that the shortcuts API might be more
    appropriate to what they are looking for.

 gtk/gtkwidget.c | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 61f1fabe3e..b2636ffa58 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -4659,9 +4659,18 @@ gtk_widget_class_set_activate_signal_from_name (GtkWidgetClass *widget_class,
  * @widget: a #GtkWidget that’s activatable
  *
  * For widgets that can be “activated” (buttons, menu items, etc.)
- * this function activates them. Activation is what happens when you
- * press Enter on a widget during key navigation. If @widget isn't
- * activatable, the function returns %FALSE.
+ * this function activates them. The activation will emit the signal
+ * set using gtk_widget_class_set_activate_signal() during class
+ * initialization.
+ *
+ * Activation is what happens when you press Enter on a widget during
+ * key navigation.
+ *
+ * If you wish to handle the activation keybinding yourself, it is
+ * recommended to use gtk_widget_class_add_shortcut() with an action
+ * created with gtk_signal_action_new().
+ *
+ * If @widget isn't activatable, the function returns %FALSE.
  *
  * Returns: %TRUE if the widget was activatable
  **/