[glibmm] Signal*: Better description of the connect*() methods.

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 836b74f233a80784bed841ccdc3f16a044809c8e
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Fri Mar 2 20:15:04 2012 +0100

    Signal*: Better description of the connect*() methods.
    
    * glib/glibmm/main.h: Mention that returning false from a bool-returning
    handler disconnects the handler. Other minor changes of the descriptions.
    Bug #669906.

 ChangeLog          |    8 ++++++++
 glib/glibmm/main.h |   49 +++++++++++++++++++++++++++++++++++--------------
 2 files changed, 43 insertions(+), 14 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index cc7dcd4..44b0736 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2012-03-02  Kjell Ahlstedt  <kjell ahlstedt bredband net>
+
+	Signal*: Better description of the connect*() methods.
+
+	* glib/glibmm/main.h: Mention that returning false from a bool-returning
+	handler disconnects the handler. Other minor changes of the descriptions.
+	Bug #669906.
+
 2012-03-02  Murray Cumming  <murrayc murrayc com>
 
 	h2defs.py: Ignore the new GDK_AVAILABLE_IN_* macros.
diff --git a/glib/glibmm/main.h b/glib/glibmm/main.h
index 908b5d1..b5fd3ab 100644
--- a/glib/glibmm/main.h
+++ b/glib/glibmm/main.h
@@ -91,15 +91,18 @@ public:
    * optimizations and more efficient system power usage.
    *
    * @code
+   * bool timeout_handler() { ... }
    * Glib::signal_timeout().connect(sigc::ptr_fun(&timeout_handler), 1000);
    * @endcode
    * is equivalent to:
    * @code
+   * bool timeout_handler() { ... }
    * const Glib::RefPtr<Glib::TimeoutSource> timeout_source = Glib::TimeoutSource::create(1000);
    * timeout_source->connect(sigc::ptr_fun(&timeout_handler));
    * timeout_source->attach(Glib::MainContext::get_default());
    * @endcode
    * @param slot A slot to call when @a interval has elapsed.
+   * If <tt>timeout_handler()</tt> returns <tt>false</tt> the handler is disconnected.
    * @param interval The timeout in milliseconds.
    * @param priority The priority of the new event source.
    * @return A connection handle, which can be used to disconnect the handler.
@@ -107,11 +110,11 @@ public:
   sigc::connection connect(const sigc::slot<bool>& slot, unsigned int interval,
                            int priority = PRIORITY_DEFAULT);
 
- /** Connects an timeout handler that runs only once.
+ /** Connects a timeout handler that runs only once.
   * This method takes a function pointer to a function with a void return
   * and no parameters. After running once it is not called again.
   *
-  * @see connect
+  * @see connect()
   * @param slot A slot to call when @a interval has elapsed. For example:
   * @code
   * void on_timeout_once()
@@ -134,15 +137,18 @@ public:
    * Subsequent timer iterations will generally run at the specified interval.
    *
    * @code
-   * Glib::signal_timeout().connect(sigc::ptr_fun(&timeout_handler), 1000);
+   * bool timeout_handler() { ... }
+   * Glib::signal_timeout().connect_seconds(sigc::ptr_fun(&timeout_handler), 5);
    * @endcode
    * is equivalent to:
    * @code
-   * const Glib::RefPtr<Glib::TimeoutSource> timeout_source = Glib::TimeoutSource::create(1000);
-   * timeout_source->connectseconds(sigc::ptr_fun(&timeout_handler));
+   * bool timeout_handler() { ... }
+   * const Glib::RefPtr<Glib::TimeoutSource> timeout_source = Glib::TimeoutSource::create(5000);
+   * timeout_source->connect(sigc::ptr_fun(&timeout_handler));
    * timeout_source->attach(Glib::MainContext::get_default());
    * @endcode
    * @param slot A slot to call when @a interval has elapsed.
+   * If <tt>timeout_handler()</tt> returns <tt>false</tt> the handler is disconnected.
    * @param interval The timeout in seconds.
    * @param priority The priority of the new event source.
    * @return A connection handle, which can be used to disconnect the handler.
@@ -152,18 +158,18 @@ public:
   sigc::connection connect_seconds(const sigc::slot<bool>& slot, unsigned int interval,
                            int priority = PRIORITY_DEFAULT);
 
- /** Connects an timeout handler that runs only once with whole second
+ /** Connects a timeout handler that runs only once with whole second
   *  granularity.
   *
   * This method takes a function pointer to a function with a void return
   * and no parameters. After running once it is not called again.
   *
-  * @see connect_seconds
+  * @see connect_seconds()
   * @param slot A slot to call when @a interval has elapsed. For example:
   * @code
   * void on_timeout_once()
   * @endcode
-  * @param interval The timeout in milliseconds.
+  * @param interval The timeout in seconds.
   * @param priority The priority of the new event source.
   */
   void connect_seconds_once(const sigc::slot<void>& slot, unsigned int interval,
@@ -186,15 +192,18 @@ public:
 
   /** Connects an idle handler.
    * @code
+   * bool idle_handler() { ... }
    * Glib::signal_idle().connect(sigc::ptr_fun(&idle_handler));
    * @endcode
    * is equivalent to:
    * @code
+   * bool idle_handler() { ... }
    * const Glib::RefPtr<Glib::IdleSource> idle_source = Glib::IdleSource::create();
    * idle_source->connect(sigc::ptr_fun(&idle_handler));
    * idle_source->attach(Glib::MainContext::get_default());
    * @endcode
    * @param slot A slot to call when the main loop is idle.
+   * If <tt>idle_handler()</tt> returns <tt>false</tt> the handler is disconnected.
    * @param priority The priority of the new event source.
    * @return A connection handle, which can be used to disconnect the handler.
    */
@@ -203,6 +212,13 @@ public:
  /** Connects an idle handler that runs only once.
   * This method takes a function pointer to a function with a void return
   * and no parameters. After running once it is not called again.
+  *
+  * @see connect()
+  * @param slot A slot to call when the main loop is idle. For example:
+  * @code
+  * void on_idle_once()
+  * @endcode
+  * @param priority The priority of the new event source.
   */
   void connect_once(const sigc::slot<void>& slot, int priority = PRIORITY_DEFAULT_IDLE);
 
@@ -221,19 +237,21 @@ public:
   explicit inline SignalIO(GMainContext* context);
 #endif
 
-  /** Connects an I/O handler.
+  /** Connects an I/O handler that watches a file descriptor.
    * @code
+   * bool io_handler(Glib::IOCondition io_condition) { ... }
    * Glib::signal_io().connect(sigc::ptr_fun(&io_handler), fd, Glib::IO_IN | Glib::IO_HUP);
    * @endcode
    * is equivalent to:
    * @code
+   * bool io_handler(Glib::IOCondition io_condition) { ... }
    * const Glib::RefPtr<Glib::IOSource> io_source = Glib::IOSource::create(fd, Glib::IO_IN | Glib::IO_HUP);
    * io_source->connect(sigc::ptr_fun(&io_handler));
    * io_source->attach(Glib::MainContext::get_default());
    * @endcode
    * @param slot A slot to call when polling @a fd results in an event that matches @a condition.
    * The event will be passed as a parameter to @a slot.
-   * If @a io_handler returns <tt>false</tt> the signal is disconnected.
+   * If <tt>io_handler()</tt> returns <tt>false</tt> the handler is disconnected.
    * @param fd The file descriptor (or a @c HANDLE on Win32 systems) to watch.
    * @param condition The conditions to watch for.
    * @param priority The priority of the new event source.
@@ -242,19 +260,21 @@ public:
   sigc::connection connect(const sigc::slot<bool,IOCondition>& slot, int fd,
                            IOCondition condition, int priority = PRIORITY_DEFAULT);
 
-  /** Connects an I/O channel.
+  /** Connects an I/O handler that watches an I/O channel.
    * @code
+   * bool io_handler(Glib::IOCondition io_condition) { ... }
    * Glib::signal_io().connect(sigc::ptr_fun(&io_handler), channel, Glib::IO_IN | Glib::IO_HUP);
    * @endcode
    * is equivalent to:
    * @code
+   * bool io_handler(Glib::IOCondition io_condition) { ... }
    * const Glib::RefPtr<Glib::IOSource> io_source = Glib::IOSource::create(channel, Glib::IO_IN | Glib::IO_HUP);
    * io_source->connect(sigc::ptr_fun(&io_handler));
    * io_source->attach(Glib::MainContext::get_default());
    * @endcode
    * @param slot A slot to call when polling @a channel results in an event that matches @a condition.
    * The event will be passed as a parameter to @a slot.
-   * If @a io_handler returns <tt>false</tt> the signal is disconnected.
+   * If <tt>io_handler()</tt> returns <tt>false</tt> the handler is disconnected.
    * @param channel The IOChannel object to watch.
    * @param condition The conditions to watch for.
    * @param priority The priority of the new event source.
@@ -278,10 +298,11 @@ public:
 #endif
   /** Connects a child watch handler.
    * @code
+   * void child_watch_handler(GPid pid, int child_status) { ... }
    * Glib::signal_child_watch().connect(sigc::ptr_fun(&child_watch_handler), pid);
    * @endcode
-   * @param slot A slot to call when child @a pid exited.
-   * @param pid The child to watch for.
+   * @param slot A slot to call when child process @a pid exited.
+   * @param pid The child process to watch for.
    * @param priority The priority of the new event source.
    * @return A connection handle, which can be used to disconnect the handler.
    */