[libsigc++2] Documentation: Mention std::function and std::bind() in more comments

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 49e753a7e2d2ce85bc090da47b80c78a24c065d6
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Sat Oct 26 10:47:25 2013 +0200

    Documentation: Mention std::function and std::bind() in more comments
    
    * sigc++/functors/macros/functor_trait.h.m4: Mention that
    SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE does not support functors
    with overloaded operator()().
    * sigc++/adaptors/macros/track_obj.h.m4:
    * sigc++/functors/macros/slot.h.m4:
    * sigc++/functors/slot_base.h:
    * sigc++/signal_base.h: Mention std::function as an alternative to
    sigc::slot.
    * sigc++/macros/signal.h.m4: connect(): Describe why the result of
    std::bind() can't be connected directly to a signal.

 sigc++/adaptors/macros/track_obj.h.m4     |    6 +++---
 sigc++/functors/macros/functor_trait.h.m4 |    2 ++
 sigc++/functors/macros/slot.h.m4          |   15 ++++++++++++---
 sigc++/functors/slot_base.h               |   13 ++++++++++++-
 sigc++/macros/signal.h.m4                 |   14 ++++++++++++--
 sigc++/signal_base.h                      |    5 ++++-
 6 files changed, 45 insertions(+), 10 deletions(-)
---
diff --git a/sigc++/adaptors/macros/track_obj.h.m4 b/sigc++/adaptors/macros/track_obj.h.m4
index f7cde4e..632b8f5 100644
--- a/sigc++/adaptors/macros/track_obj.h.m4
+++ b/sigc++/adaptors/macros/track_obj.h.m4
@@ -136,9 +136,9 @@ namespace sigc {
 
 /** @defgroup track_obj track_obj()
  * track_obj() tracks trackable objects, referenced from a functor.
- * It can be useful when you assign a C++11 lambda expression to a slot, or connect
- * it to a signal, and the lambda expression contains references to sigc::trackable
- * derived objects.
+ * It can be useful when you assign a C++11 lambda expression or a std::function<>
+ * to a slot, or connect it to a signal, and the lambda expression or std::function<>
+ * contains references to sigc::trackable derived objects.
  *
  * The functor returned by sigc::track_obj() is formally an adaptor, but it does
  * not alter the signature, return type or behaviour of the supplied functor.
diff --git a/sigc++/functors/macros/functor_trait.h.m4 b/sigc++/functors/macros/functor_trait.h.m4
index 915e27d..813d8d9 100644
--- a/sigc++/functors/macros/functor_trait.h.m4
+++ b/sigc++/functors/macros/functor_trait.h.m4
@@ -197,6 +197,8 @@ struct functor_trait<T_functor,false>          \
  * }
  * @endcode
  *
+ * Functors with overloaded operator()() are not supported.
+ *
  * @newin{2,2,11}
  *
  * You can't use both SIGC_FUNCTORS_HAVE_RESULT_TYPE and
diff --git a/sigc++/functors/macros/slot.h.m4 b/sigc++/functors/macros/slot.h.m4
index 1a125ef..7162e63 100644
--- a/sigc++/functors/macros/slot.h.m4
+++ b/sigc++/functors/macros/slot.h.m4
@@ -28,7 +28,7 @@ define([SLOT_N],[dnl
 FOR(1,$1,[
  * - @e T_arg%1 Argument type used in the definition of operator()(). The default @p nil means no argument.])
  *
- * To use simply assign the slot to the desired functor. If the functor
+ * 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
  * will invoke the functor with minimal copies.
@@ -109,7 +109,7 @@ ifelse($1, $2,[dnl
 FOR(1,$1,[
  * - @e T_arg%1 Argument type used in the definition of operator()(). The default @p nil means no argument.])
  *
- * To use, simply assign the slot to the desired functor. If the functor
+ * 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
  * will invoke the functor with minimal copies.
@@ -119,10 +119,19 @@ FOR(1,$1,[
  * @par Example:
  * @code
  * void foo(int) {}
- * sigc::slot<void, long> s = sigc::ptr_fun(&foo);
+ * sigc::slot<void, int> s = sigc::ptr_fun(&foo);
  * 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
+ *
  * @ingroup slot
  */
 template <LIST(class T_return, LOOP(class T_arg%1 = nil, $1))>],[dnl
diff --git a/sigc++/functors/slot_base.h b/sigc++/functors/slot_base.h
index 7081238..3a23f34 100644
--- a/sigc++/functors/slot_base.h
+++ b/sigc++/functors/slot_base.h
@@ -177,7 +177,7 @@ struct SIGC_API slot_do_unbind
  * Use the sigc::mem_fun() and sigc::ptr_fun() template functions to get a sigc::slot, like so:
  *
  * @code
- * sigc::slot<void, int> sl = sigc::mem_fun(someobj,& SomeClass::somemethod);
+ * sigc::slot<void, int> sl = sigc::mem_fun(someobj, &SomeClass::somemethod);
  * @endcode
  *
  * or
@@ -196,6 +196,17 @@ 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:
+ * @code
+ * std::function<void(int)> fn = &somefunction;
+ * m_Dialog.signal_response().connect(fn);
+ * @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,
+ *   those objects will not be tracked, unless you also use sigc::track_obj().
+ *
  * @ingroup sigcfunctors
  */
 
diff --git a/sigc++/macros/signal.h.m4 b/sigc++/macros/signal.h.m4
index 6d33794..03deae0 100644
--- a/sigc++/macros/signal.h.m4
+++ b/sigc++/macros/signal.h.m4
@@ -319,12 +319,22 @@ public:
 
   /** Add a slot to the list of slots.
    * Any functor or slot may be passed into connect().
-   * It will be converted into a slot implicitely.
+   * It will be converted into a slot implicitly.
    * The returned iterator may be stored for disconnection
    * of the slot at some later point. It stays valid until
    * the slot is removed from the list of slots. The iterator
-   * can also be implicitely converted into a sigc::connection object
+   * can also be implicitly converted into a sigc::connection object
    * that may be used safely beyond the life time of the slot.
+   *
+   * std::function<> and C++11 lambda expressions are functors.
+   * These are examples of functors that can be connected to a signal.
+   *
+   * %std::bind() creates a functor, but this functor typically has an
+   * %operator()() which is a variadic template.
+   * #SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE can't deduce the result type
+   * of such a functor. If you first assign the return value of %std::bind()
+   * to a std::function, you can connect the std::function to a signal.
+   *
    * @param slot_ The slot to add to the list of slots.
    * @return An iterator pointing to the new slot in the list.
    */
diff --git a/sigc++/signal_base.h b/sigc++/signal_base.h
index 3b972ab..841f99d 100644
--- a/sigc++/signal_base.h
+++ b/sigc++/signal_base.h
@@ -242,9 +242,12 @@ private:
  * For compile time type safety a list of template arguments
  * must be provided for the signal template that determines the
  * parameter list for emission. Functors and closures are converted
- * into slots implicitely on connection, triggering compiler errors
+ * into slots implicitly on connection, triggering compiler errors
  * if the given functor or closure cannot be invoked with the
  * parameter list of the signal to connect to.
+ *
+ * Almost any functor with the correct signature can be converted to a sigc::slot
+ * and connected to a signal. See @ref slot "Slots" and sigc::signal::connect().
  */
 
 /** Base class for the sigc::signal# templates.