slot, signal docs: Describe the slot<void(int)> syntax more

kjellahl · kjellahl · commit 14d2ed399ec3 · 2023-05-27T12:41:34.000+02:00
See #86
diff --git a/sigc++/functors/macros/slot.h.m4 b/sigc++/functors/macros/slot.h.m4
@@ -37,6 +37,11 @@ FOR(1,$1,[
  *
  * You should use the more convenient unnumbered sigc::slot template.
  *
+ * @deprecated Please use the syntax similar to that used by std::function<>:
+ * @code
+ * sigc::slot<void(bool, int)> some_slot;
+ * @endcode
+ *
  * @ingroup slot
  */
 template <LIST(class T_return, LOOP(class T_arg%1, $1))>
@@ -561,7 +566,7 @@ FOR(0,eval(CALL_SIZE-1),[[SLOT(%1,CALL_SIZE)]])
  * sigc::slot<void(bool, int)> some_slot;
  * @endcode
  *
- * Alternatively, you may use this syntax:
+ * Alternatively, you may use this deprecated syntax:
  * @code
  * sigc::slot<void, bool, int> some_slot;
  * @endcode
diff --git a/sigc++/functors/slot_base.h b/sigc++/functors/slot_base.h
@@ -186,16 +186,20 @@ struct SIGC_API slot_do_unbind
  *
  * Use the sigc::mem_fun() or 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
  * @code
- * sigc::slot<void, int> sl = sigc::ptr_fun(&somefunction);
+ * sigc::slot<void(int)> sl = sigc::ptr_fun(&somefunction);
  * @endcode
  * or, in gtkmm,
  * @code
  * m_Button.signal_clicked().connect( sigc::mem_fun(*this, &MyWindow::on_button_clicked) );
  * @endcode
+ * Alternatively, you may use this deprecated syntax:
+ * @code
+ * sigc::slot<void, int> sl = sigc::mem_fun(someobj, &SomeClass::somemethod);
+ * @endcode
  *
  * The compiler will complain if SomeClass::somemethod, etc. have the wrong signature.
  *
@@ -211,7 +215,7 @@ struct SIGC_API slot_do_unbind
  * 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);
+ * sigc::slot<void(int)> sl = sigc::mem_fun(someobj, &SomeClass::somemethod);
  * @endcode
  * is not equivalent to
  * @code
@@ -237,10 +241,11 @@ struct SIGC_API slot_do_unbind
  *
  * If you connect a C++11 lambda expression or a std::function<> instance to
  * a signal or assign it to a slot,
- * - With libsigc++ versions before 2.6, if the return type is not void,
+ * - with libsigc++ versions before 2.6, 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().
+ *   those objects will not be tracked, unless you also use sigc::track_object()
+ *   or sigc::track_obj().
  *
  * @ingroup sigcfunctors
  */
diff --git a/sigc++/macros/signal.h.m4 b/sigc++/macros/signal.h.m4
@@ -310,6 +310,11 @@ FOR(1,$1,[
  *
  * You should use the more convenient unnumbered sigc::signal template.
  *
+ * @deprecated Please use the syntax similar to that used by std::function<>:
+ * @code
+ * sigc::signal<void(bool, int)> some_signal;
+ * @endcode
+ *
  * @ingroup signal
  */
 template <LIST(class T_return, LOOP(class T_arg%1, $1), class T_accumulator=nil)>
@@ -474,7 +479,7 @@ FOR(1,$1,[
  *
  * @deprecated Please use the syntax similar to that used by std::function<>:
  * @code
- * sigc::slot<void(bool, int)> some_slot;
+ * sigc::signal<void(bool, int)> some_signal;
  * @endcode
  *
  * @ingroup signal
@@ -489,7 +494,7 @@ class signal],[dnl
  *
  * @deprecated Please use the syntax similar to that used by std::function<>:
  * @code
- * sigc::slot<void(bool, int)> some_slot;
+ * sigc::signal<void(bool, int)> some_signal;
  * @endcode
 ifelse($1, $2,[dnl
  *
@@ -586,7 +591,9 @@ ifelse($1, $2,[dnl
 };
 
 /**
- * This specialization allow use of the  sigc::signal<R(Args...)> syntax,
+ * This specialization allows use of the sigc::signal<R(Args...)> syntax.
+ *
+ * @ingroup signal
  */
 template <LIST(class T_return, LOOP(class T_arg%1, $1))>
 class signal<T_return(LIST(LOOP(T_arg%1, $1)))>
diff --git a/sigc++/signal_base.h b/sigc++/signal_base.h
@@ -264,7 +264,7 @@ struct temp_slot_list
  * class MyClass
  * {
  * public:
- *   typedef sigc::signal<void> MySignalType;
+ *   using MySignalType = sigc::signal<void()>;
  *   MySignalType get_my_signal() { return m_my_signal; }
  * private:
  *   MySignalType m_my_signal;
