Improve the documentation of mem_fun()

Kjell Ahlstedt · Kjell Ahlstedt · commit 1d5c9084f285 · 2016-03-02T18:37:09.000+01:00
* 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&lt;....&gt; s = sigc::mem_fun(....)'.
The confusing documentation was noted by Andrejs Hanins on libsigc-list.
diff --git 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
@@ -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
