[glibmm] Glib::SignalProxy::connect(): Improve the documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 7bd0fa6fa6404ff73d338c26543e114dc1031fc7
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Thu Apr 20 18:17:24 2017 +0200

    Glib::SignalProxy::connect(): Improve the documentation
    
    Mention that the 'after' parameter can be important. Bug 126213

 glib/glibmm/signalproxy.h |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)
---
diff --git a/glib/glibmm/signalproxy.h b/glib/glibmm/signalproxy.h
index 063bd91..d60f749 100644
--- a/glib/glibmm/signalproxy.h
+++ b/glib/glibmm/signalproxy.h
@@ -153,6 +153,17 @@ public:
    *
    * For instance, connect( sigc::mem_fun(*this, &TheClass::on_something) );
    *
+   * By default, the signal handler will be called after the default signal handler.
+   * This is often fine, but for some signal handlers that return a value, it can
+   * be necessary to connect before the default signal handler.
+   * Examples:
+   * - Gio::Application::signal_command_line() calls only one signal handler.
+   *   A handler connected after the default handler will never be called.
+   * - X event signals, such as Gtk::Widget::signal_button_press_event(), stop
+   *   calling signal handlers as soon as a called handler returns <tt>true</tt>.
+   *   If the default handler returns <tt>true</tt>, a handler connected after it
+   *   will not be called.
+   *
    * @param slot The signal handler, usually created with sigc::mem_fun() or sigc::ptr_fun().
    * @param after Whether this signal handler should be called before or after the default signal
    * handler.
@@ -288,6 +299,17 @@ public:
    *
    * For instance, connect( sigc::mem_fun(*this, &TheClass::on_something) );
    *
+   * By default, the signal handler will be called after the default signal handler.
+   * This is often fine, but for some signal handlers that return a value, it can
+   * be necessary to connect before the default signal handler.
+   * Examples:
+   * - Gio::Application::signal_command_line() calls only one signal handler.
+   *   A handler connected after the default handler will never be called.
+   * - X event signals, such as Gtk::Widget::signal_button_press_event(), stop
+   *   calling signal handlers as soon as a called handler returns <tt>true</tt>.
+   *   If the default handler returns <tt>true</tt>, a handler connected after it
+   *   will not be called.
+   *
    * @param slot The signal handler, usually created with sigc::mem_fun() or sigc::ptr_fun().
    * @param after Whether this signal handler should be called before or after the default signal
    * handler.