Imported Upstream version 2.99.2

[platform/upstream/libsigc++.git] / sigc++ / functors / slot.h

diff --git a/sigc++/functors/slot.h b/sigc++/functors/slot.h
index ad23ab1..43176a1 100644 (file)
--- a/sigc++/functors/slot.h
+++ b/sigc++/functors/slot.h
@@ -129,25 +129,33 @@ struct slot_call
 // slot's specialization of the visitor struct.
 
 /** Converts an arbitrary functor to a unified type which is opaque.
- * sigc::slot itself is a functor or to be more precise a closure. It contains
+ * sigc::slot itself is a functor or, to be more precise, a closure. It contains
  * a single, arbitrary functor (or closure) that is executed in operator()().
  *
  * The template arguments determine the function signature of operator()():
- * - @e T_return The return type of operator()(). * - @e T_arg Argument types used in the definition of operator()().
+ * - @e T_return The return type of operator()().
+ * - @e T_arg Argument types used in the definition of operator()().
  *
- * To use simply assign the desired functor to the slot. If the functor
+ * For instance, to declare a slot that returns void and takes two parameters
+ * of bool and int:
+ * @code
+ * sigc::slot<void(bool, int)> some_slot;
+ * @endcode
+ *
+ * To use, simply assign the desired functor to the slot. If the functor
  * is not compatible with the parameter list defined with the template
- * arguments compiler errors are triggered. When called the slot
+ * arguments then compiler errors are triggered. When called, the slot
  * will invoke the functor with minimal copies.
  * block() and unblock() can be used to block the functor's invocation
  * from operator()() temporarily.
  *
- * You should use the more convenient unnumbered sigc::slot template.
- *
  * @ingroup slot
  */
 template <class T_return, class... T_arg>
-class slot
+class slot;
+
+template <class T_return, class... T_arg>
+class slot<T_return(T_arg...)>
   : public slot_base
 {
 public:
@@ -225,8 +233,23 @@ public:
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visitor<>::do_visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
- * The function overloads for sigc::slot are similar to the function
- * overloads for sigc::slot. See the description of those overloads.
+ *
+ * There are three function overloads for sigc::slot.
+ *
+ * The first two overloads are very specialized. They handle the (probably unusual)
+ * case when the functor, stored in a slot, contains a slot. They are invoked from
+ * the constructor, destructor or destroy() method of typed_slot_rep.
+ * The first overload, called from the constructor of the outer slot, sets
+ * the outer slot as the parent of the inner slot. The second overload, called from
+ * the destructor or destroy() of the outer slot, unsets the parent of the inner slot.
+ * When an object referenced from the inner slot is deleted, the inner slot calls
+ * its slot_rep::disconnect(), which calls the outer slot's slot_rep::notify().
+ * The outer slot is informed just as if one of its directly referenced objects
+ * had been deleted. Result: The outer slot is disconnected from its parent,
+ * if any (for instance a sigc::signal).
+ * See https://bugzilla.gnome.org/show_bug.cgi?id=755003
+ *
+ * The third overload is identical to do_visit_each() in visitor's primary template.
  *
  * @ingroup slot
  */
@@ -256,8 +279,6 @@ struct visitor<slot<T_return, T_arg...>>
 };
 #endif // DOXYGEN_SHOULD_SKIP_THIS
 
-
 } /* namespace sigc */
 
-
 #endif /* _SIGC_FUNCTORS_SLOT_H_ */