[libsigc++2] Documentation: Talk less about std::function

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 62617fc598292925117e63e372b138caebbca1f0
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Oct 28 16:20:35 2013 +0100

    Documentation: Talk less about std::function
    
    * sigc++/functors/macros/slot.h.m4:
    * sigc++/functors/slot_base.h: Remove the examples with std::function.
    Add an example with a C++11 lambda expression.
    https://mail.gnome.org/archives/libsigc-list/2013-October/msg00003.html

 sigc++/functors/macros/slot.h.m4 |   11 +++--------
 sigc++/functors/slot_base.h      |   22 ++++++++++++++--------
 2 files changed, 17 insertions(+), 16 deletions(-)
---
diff --git a/sigc++/functors/macros/slot.h.m4 b/sigc++/functors/macros/slot.h.m4
index 7162e63..4a85e44 100644
--- a/sigc++/functors/macros/slot.h.m4
+++ b/sigc++/functors/macros/slot.h.m4
@@ -123,14 +123,9 @@ FOR(1,$1,[
  * s(19);
  * @endcode
  *
- * It is often possible to replace sigc::slot<> by the C++11 class std::function<>.
- *
- * @par Example:
- * @code
- * void foo(int) {}
- * std::function<void(int)> f = &foo;
- * f(19);
- * @endcode
+ * sigc::slot<> is similar to std::function<>. If you're going to assign the
+ * resulting functor to a sigc::slot or connect it to a sigc::signal, it's better
+ * not to use std::function. It would become un unnecessary extra wrapper.
  *
  * @ingroup slot
  */
diff --git a/sigc++/functors/slot_base.h b/sigc++/functors/slot_base.h
index 3a23f34..69acef7 100644
--- a/sigc++/functors/slot_base.h
+++ b/sigc++/functors/slot_base.h
@@ -171,8 +171,8 @@ struct SIGC_API slot_do_unbind
 
 /** @defgroup slot Slots
  * Slots are type-safe representations of callback methods and functions.
- * A Slot can be constructed from any function, regardless of whether it is a global function,
- * a member method, static, or virtual.
+ * A Slot can be constructed from any function object or function, regardless of
+ * whether it is a global function, a member method, static, or virtual.
  *
  * Use the sigc::mem_fun() and sigc::ptr_fun() template functions to get a sigc::slot, like so:
  *
@@ -196,15 +196,21 @@ struct SIGC_API slot_do_unbind
  *
  * You can also pass slots as method parameters where you might normally pass a function pointer.
  *
- * It is often possible to replace sigc::slot<> by the C++11 class std::function<>, for instance:
+ * A C++11 lambda expression is a functor (function object). It is automatically
+ * wrapped in a slot, if it is connected to a signal.
  * @code
- * std::function<void(int)> fn = &somefunction;
- * m_Dialog.signal_response().connect(fn);
+ * auto on_response = [&someobj] (int response_id)
+ *   {
+ *     someobj.somemethod(response_id);
+ *     somefunction(response_id);
+ *   };
+ * m_Dialog.signal_response().connect(on_response);
  * @endcode
  *
- * If you connect an std::function<> instance to a signal or assign it to a slot,
- * - if the return type is not void, you must use the #SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE macro;
- * - if your function, somefunction(), contains references to sigc::trackable derived objects,
+ * If you connect a C++11 lambda expression or a std::function<> instance to
+ * a signal or assign it to a slot,
+ * - if the return type is not void, you must use the #SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE macro,
+ * - if your functor contains references to sigc::trackable derived objects,
  *   those objects will not be tracked, unless you also use sigc::track_obj().
  *
  * @ingroup sigcfunctors