[libsigc++2] Mention visit_each() in the documentation of sigc::adapts.

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 0439751f40e126918e5fa0f36415930b315dd7c8
Author: Thomas Rydzynski <qsorix rydznet pl>
Date:   Thu Jul 21 18:53:27 2011 +0200

    Mention visit_each() in the documentation of sigc::adapts.
    
    * sigc++/adaptors/macros/adaptor_trait.h.m4: Mention that a user-supplied
    adaptor must be accompanied by a specialization of template function
    visit_each(). Correct some minor errors in the example of a user-supplied
    adaptor. Bug #486373.

 ChangeLog                                 |   11 ++++++++++-
 sigc++/adaptors/macros/adaptor_trait.h.m4 |   26 +++++++++++++++++++++-----
 2 files changed, 31 insertions(+), 6 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 64a7ff4..851dd97 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,17 @@
+2011-07-21  Thomas Rydzynski  <qsorix rydznet pl>
+
+	Mention visit_each() in the documentation of sigc::adapts.
+
+	* sigc++/adaptors/macros/adaptor_trait.h.m4: Mention that a user-supplied
+	adaptor must be accompanied by a specialization of template function
+	visit_each(). Correct some minor errors in the example of a user-supplied
+	adaptor. Bug #486373.
+
 2011-07-19  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	Add a test case for the previous commit.
 
-  * tests/Makefile.am:
+	* tests/Makefile.am:
 	* tests/test_bind_refptr.cc: A version of this test is also in glibmm.
 	Note that this includes a copy/paste of RefPtr.
 	See Bug #564005#14
diff --git a/sigc++/adaptors/macros/adaptor_trait.h.m4 b/sigc++/adaptors/macros/adaptor_trait.h.m4
index 2d1fa06..2456904 100644
--- a/sigc++/adaptors/macros/adaptor_trait.h.m4
+++ b/sigc++/adaptors/macros/adaptor_trait.h.m4
@@ -240,8 +240,8 @@ struct adaptor_trait<T_functor, false>
  *
  * @par Example of a simple adaptor:
  * @code
- * template <T_functor>
- * struct my_adpator : public sigc::adapts<T_functor>
+ * template <class T_functor>
+ * struct my_adaptor : public sigc::adapts<T_functor>
  * {
  *   template <class T_arg1=void, class T_arg2=void>
  *   struct deduce_result_type
@@ -259,13 +259,29 @@ struct adaptor_trait<T_functor, false>
  *   typename deduce_result_type<T_arg1, T_arg2>::type
  *   operator()(T_arg1 _A_arg1, class T_arg2) const;
  *
- *   explicit adaptor_functor(const T_functor& _A_functor) // Constructs a my_functor object that wraps the passed functor.
+ *   // Constructs a my_adaptor object that wraps the passed functor.
+ *   // Initializes adapts<T_functor>::functor_, which is invoked from operator()().
+ *   explicit my_adaptor(const T_functor& _A_functor)
  *     : sigc::adapts<T_functor>(_A_functor) {}
- *
- *   mutable T_functor functor_; // Functor that is invoked from operator()().
  * };
+ *
+ * template <class T_action, class T_functor>
+ * void visit_each(const T_action& _A_action,
+ *                 const my_adaptor<T_functor>& _A_target)
+ * {
+ *   visit_each(_A_action, _A_target.functor_);
+ * }
  * @endcode
  *
+ * If you implement your own adaptor, you must also provide your specialization
+ * of visit_each<>() that will forward the call to the functor(s) your
+ * adapter is wrapping. Otherwise, pointers stored within the functor won't be
+ * invalidated when a sigc::trackable object is destroyed and you can end up
+ * executing callbacks on destroyed objects.
+ *
+ * Your adaptor and your specialization of visit_each<>() must be in the same
+ * namespace.
+ *
  * @ingroup adaptors
  */
 template <class T_functor>