connection: Improve the class documentation

kjellahl · kjellahl · commit 9a48bad8ac2e · 2023-05-31T17:10:45.000+02:00
Fixes #88
diff --git a/sigc++/connection.h b/sigc++/connection.h
@@ -23,17 +23,20 @@
 
 namespace sigc {
 
-/** Convinience class for safe disconnection.
- * Iterators must not be used beyond the lifetime of the list
- * they work on. A connection object can be created from a
- * slot list iterator and may safely be used to disconnect
- * the referred slot at any time (disconnect()). If the slot
- * has already been destroyed, disconnect() does nothing. empty() or
- * operator bool() can be used to test whether the connection is
- * still active. The connection can be blocked (block(), unblock()).
+/** Convenience class for safe disconnection.
  *
- * This is possible because the connection object gets notified
- * when the referred slot dies (notify()).
+ * sigc::signal::connect() returns a slot list iterator.
+ * Iterators must not be used beyond the lifetime of the list they work on.
+ * A connection object can be created from a slot list iterator.
+ * @code
+ * sigc::connection conn = sig.connect(sigc::mem_fun(a, &A::foo));
+ * @endcode
+ * The connection may safely be used to disconnect the referred slot
+ * at any time (disconnect()). If the slot has already been destroyed,
+ * disconnect() does nothing. This is possible because the connection
+ * object gets notified when the referred slot dies (notify()). empty() or
+ * operator bool() can be used to test whether the connection is still active.
+ * The connection can be blocked (block(), unblock()).
  *
  * @ingroup signal
  */
