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.

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