[libsigc++2] Improve the documentation of mem_fun()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 1d5c9084f2851c1485ecdb7aa99519bf49e1d57a
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Wed Mar 2 18:37:09 2016 +0100

    Improve the documentation of mem_fun()
    
    * sigc++/functors/macros/mem_fun.h.m4:
    * sigc++/functors/slot_base.h: Make it clear that mem_fun() does not return
    a slot, and 'auto s = sigc::mem_fun(....)' is not equivalent to
    'sigc::slot<....> s = sigc::mem_fun(....)'.
    The confusing documentation was noted by Andrejs Hanins on libsigc-list.

 sigc++/functors/macros/mem_fun.h.m4 |    8 ++++++--
 sigc++/functors/slot_base.h         |   19 ++++++++++++-------
 2 files changed, 18 insertions(+), 9 deletions(-)
---
diff --git a/sigc++/functors/macros/mem_fun.h.m4 b/sigc++/functors/macros/mem_fun.h.m4
index 9cb6270..90d1889 100644
--- a/sigc++/functors/macros/mem_fun.h.m4
+++ b/sigc++/functors/macros/mem_fun.h.m4
@@ -199,8 +199,10 @@ namespace sigc {
  * mem_fun() is used to convert a pointer to a method to a functor.
  *
  * Optionally, a reference or pointer to an object can be bound to the functor.
- * Note that only if the object type inherits from sigc::trackable is
- * the slot automatically cleared when the object goes out of scope!
+ *
+ * @note Only if the object type inherits from sigc::trackable, and the
+ * functor returned from mem_fun() is assigned to a sigc::slot, is the functor
+ * automatically cleared when the object goes out of scope!
  *
  * If the member function pointer is to an overloaded type, you must specify
  * the types using template arguments starting with the first argument.
@@ -214,6 +216,8 @@ namespace sigc {
  * };
  * foo my_foo;
  * sigc::slot<void, int> sl = sigc::mem_fun(my_foo, &foo::bar);
+ * // Note: f is not a slot. It will not be invalidated when my_foo is deleted.
+ * auto f = sigc::mem_fun(my_foo, &foo::bar); // Usually not what you want.
  * @endcode
  *
  * For const methods mem_fun() takes a const reference or pointer to an object.
diff --git a/sigc++/functors/slot_base.h b/sigc++/functors/slot_base.h
index 8ecd086..5dd4d22 100644
--- a/sigc++/functors/slot_base.h
+++ b/sigc++/functors/slot_base.h
@@ -179,23 +179,18 @@ 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 object or function, regardless of
+ * 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:
- *
  * @code
  * sigc::slot<void, int> sl = sigc::mem_fun(someobj, &SomeClass::somemethod);
  * @endcode
- *
  * or
- *
  * @code
  * sigc::slot<void, int> sl = sigc::ptr_fun(&somefunction);
  * @endcode
- *
- * or
- *
+ * or, in gtkmm,
  * @code
  * m_Button.signal_clicked().connect( sigc::mem_fun(*this, &MyWindow::on_button_clicked) );
  * @endcode
@@ -204,6 +199,16 @@ struct SIGC_API slot_do_unbind
  *
  * You can also pass slots as method parameters where you might normally pass a function pointer.
  *
+ * sigc::mem_fun() and sigc::ptr_fun() return functors, but those functors are
+ * not slots.
+ * @code
+ * sigc::slot<void, int> sl = sigc::mem_fun(someobj, &SomeClass::somemethod);
+ * @endcode
+ * is not equivalent to
+ * @code
+ * auto sl = sigc::mem_fun(someobj, &SomeClass::somemethod); // Not a slot!
+ * @endcode
+ *
  * 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