[libsigcplusplus] slot: Reinsert a comment that disappeared accidentally

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 878d72335bdd9491334660075697f362a2049dd6
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Wed Mar 16 13:34:31 2016 +0100

    slot: Reinsert a comment that disappeared accidentally
    
    The description of slot's specialization of visitor<>::do_visit_each<>()
    disappeared by mistake when the slot# classes were removed.

 sigc++/functors/slot.h |   22 +++++++++++++++++-----
 1 files changed, 17 insertions(+), 5 deletions(-)
---
diff --git a/sigc++/functors/slot.h b/sigc++/functors/slot.h
index 6661c6a..43176a1 100644
--- a/sigc++/functors/slot.h
+++ b/sigc++/functors/slot.h
@@ -230,12 +230,26 @@ 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
  */
@@ -265,8 +279,6 @@ struct visitor<slot<T_return, T_arg...>>
 };
 #endif // DOXYGEN_SHOULD_SKIP_THIS
 
-
 } /* namespace sigc */
 
-
 #endif /* _SIGC_FUNCTORS_SLOT_H_ */