[libsigc++2] Documentation: Emphasize that signals are ref counted

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 1b05b5a573d737e3c29056d449ebc299c26d22e3
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Jul 28 09:52:41 2014 +0200

    Documentation: Emphasize that signals are ref counted
    
    * sigc++/signal_base.h: Emphasize that a sigc::signal holds a pointer to
    a ref counted signal_impl. Bug #611941.

 sigc++/signal_base.h |   19 +++++++++++++++++++
 1 files changed, 19 insertions(+), 0 deletions(-)
---
diff --git a/sigc++/signal_base.h b/sigc++/signal_base.h
index 9a99eeb..100eede 100644
--- a/sigc++/signal_base.h
+++ b/sigc++/signal_base.h
@@ -233,6 +233,20 @@ private:
  *
  * When signals are copied they share the underlying information,
  * so you can have a protected/private sigc::signal member and a public accessor method.
+ * A sigc::signal is a kind of reference-counting pointer. It's similar to
+ * std::shared_ptr<>, although sigc::signal is restricted to holding a pointer to
+ * a sigc::internal::signal_impl object that contains the implementation of the signal.
+ *
+ * @code
+ * class MyClass
+ * {
+ * public:
+ *   typedef sigc::signal<void> MySignalType;
+ *   MySignalType get_my_signal() { return m_my_signal; }
+ * private:
+ *   MySignalType m_my_signal;
+ * };
+ * @endcode
  *
  * signal and slot objects provide the core functionality of this
  * library. A slot is a container for an arbitrary functor.
@@ -255,6 +269,11 @@ private:
  * when first connecting a slot to the signal. This ensures that empty signals
  * don't waste memory.
  *
+ * sigc::internal::signal_impl is reference-counted. When a sigc::signal# object
+ * is copied, the reference count of its sigc::internal::signal_impl object is
+ * incremented. Both sigc::signal# objects then refer to the same
+ * sigc::internal::signal_impl object.
+ *
  * @ingroup signal
  */
 struct SIGC_API signal_base : public trackable