Added some documentation.

2004-07-09  Murray Cumming  <murrayc@murrayc.com>

        * glib/glibmm/signalproxy.h.m4: Added some documentation.

4 files changed, 59 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index c897056c..12afe7df 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-07-09  Murray Cumming  <murrayc@murrayc.com>
+
+	* glib/glibmm/signalproxy.h.m4: Added some documentation.
+
 2004-06-20  Daniel Elstner  <daniel.elstner@gmx.net>
 
 	* glib/glibmm/objectbase.cc: Spring cleaning.
diff --git a/glib/glibmm/signalproxy_connectionnode.cc b/glib/glibmm/signalproxy_connectionnode.cc
index 0a78ad84..07586255 100644
--- a/glib/glibmm/signalproxy_connectionnode.cc
+++ b/glib/glibmm/signalproxy_connectionnode.cc
@@ -46,7 +46,7 @@ void* SignalProxyConnectionNode::notify(void* data)
   SignalProxyConnectionNode* conn = static_cast<SignalProxyConnectionNode*>(data);
 
   // if there is no object, this call was triggered from destroy_notify_handler().
-  if (conn->object_)
+  if(conn && conn->object_)
   {
     GObject* o = conn->object_;
     conn->object_ = 0;
@@ -70,7 +70,7 @@ void SignalProxyConnectionNode::destroy_notify_handler(gpointer data, GClosure*)
   SignalProxyConnectionNode* conn = static_cast<SignalProxyConnectionNode*>(data);
 
   // if there is no object, this call was triggered from notify().
-  if (conn->object_)
+  if (conn && conn->object_)
   {
     // the object has already lost track of this object.
     conn->object_ = 0;
diff --git a/glib/glibmm/signalproxy_connectionnode.h b/glib/glibmm/signalproxy_connectionnode.h
index 0dd84a80..e0a8f5eb 100644
--- a/glib/glibmm/signalproxy_connectionnode.h
+++ b/glib/glibmm/signalproxy_connectionnode.h
@@ -32,12 +32,16 @@ namespace Glib
 {
 
 /** SignalProxyConnectionNode is a connection node for use with SignalProxy.
-  * It lives between the layer of Gtk+ and SigC++.
+  * It lives between the layer of Gtk+ and libsigc++.
   * It is very much an internal class.
   */
 class SignalProxyConnectionNode
 {
 public:
+
+  /** @param slot The signal handler for the GTK+ signal.
+   *
+   */
   SignalProxyConnectionNode(const sigc::slot_base& slot, GObject* gobject);
 
   /** Callback that is executed when the slot becomes invalid.
@@ -50,7 +54,7 @@ public:
    * @param data The SignalProxyConnectionNode object (@p this).
    * @param closure The glib closure object.
    */
-  static void destroy_notify_handler(gpointer data, GClosure *closure);
+  static void destroy_notify_handler(gpointer data, GClosure* closure);
 
   gulong connection_id_;
   sigc::slot_base slot_;
diff --git a/glib/src/signalproxy.h.m4 b/glib/src/signalproxy.h.m4
index 6ba9fdb0..bf3d55ba 100644
--- a/glib/src/signalproxy.h.m4
+++ b/glib/src/signalproxy.h.m4
@@ -77,10 +77,15 @@ private:
 
 
 // shared portion of a Signal
-//   The proxy just serves to hold the name of the signal and the object
-//   which is to be connected.  Actually, proxies are controlled by
-//   the template derivatives, which serve as gatekeepers for the
-//   types allowed on a particular signal.
+/** The SignalProxy provides an API similar to sigc::signal that can be used to
+ * connect sigc::slots to glib signals.
+ *
+ * This holds the name of the glib signal and the object
+ * which might emit it. Actually, proxies are controlled by
+ * the template derivatives, which serve as gatekeepers for the
+ * types allowed on a particular signal.
+ *
+ */
 class SignalProxyNormal : public SignalProxyBase
 {
 public:
@@ -96,14 +101,37 @@ public:
 #endif
 
 protected:
+
+  /** Create a proxy for a signal that can be emitted by @a obj.
+   * @param obj The object that can emit the signal.
+   * @param info Information about the signal, including its name, and the C callbacks that should be called by glib.
+   */
   SignalProxyNormal(Glib::ObjectBase* obj, const SignalProxyInfo* info);
 
+  /** Connects a signal to a generic signal handler. This is called by connect() in derived SignalProxy classes.
+   *
+   * @param slot The signal handler, usually created with sigc::mem_fun(), or sigc::ptr_fun().
+   * @param after Whether this signal handler should be called before or after the default signal handler.
+   */
   sigc::slot_base& connect_(const sigc::slot_base& slot, bool after);
+
+  /** Connects a signal to a signal handler without a return value.
+   * This is called by connect() in derived SignalProxy classes.
+   *
+   * By default, the signal handler will be called before the default signal handler,
+   * in which case any return value would be replaced anyway by that of the later signal handler.
+   *
+   * @param slot The signal handler, which should have a void return type, usually created with sigc::mem_fun(), or sigc::ptr_fun().
+   * @param after Whether this signal handler should be called before or after the default signal handler.
+   */
   sigc::slot_base& connect_notify_(const sigc::slot_base& slot, bool after);
 
 private:
   const SignalProxyInfo* info_;
 
+  //TODO: We could maybe replace both connect_ and connect_notify_ with this in future, because they don't do anything extra.
+  /** This is called by connect_ and connect_impl_.
+   */
   sigc::slot_base& connect_impl_(GCallback callback, const sigc::slot_base& slot, bool after);
 
   // no copy assignment
@@ -132,9 +160,24 @@ public:
   [SignalProxy]NUM($1)(ObjectBase* obj, const SignalProxyInfo* info)
     : SignalProxyNormal(obj, info) {}
 
+  /** Connects a signal to a signal handler.
+   * For instance, connect( sigc::mem_fun(*this, &TheClass::on_something) );
+   *
+   * @param slot The signal handler, usually created with sigc::mem_fun(), or sigc::ptr_fun().
+   * @param after Whether this signal handler should be called before or after the default signal handler.
+   */
   sigc::connection connect(const SlotType& slot, bool after = true)
     { return sigc::connection(connect_(slot, after)); }
 
+  /** Connects a signal to a signal handler without a return value.
+   * By default, the signal handler will be called before the default signal handler,
+   * in which case any return value would be replaced anyway by that of the later signal handler.
+   *
+   * For instance, connect( sigc::mem_fun(*this, &TheClass::on_something) );
+   *
+   * @param slot The signal handler, which should have a void return type, usually created with sigc::mem_fun(), or sigc::ptr_fun().
+   * @param after Whether this signal handler should be called before or after the default signal handler.
+   */
   sigc::connection connect_notify(const VoidSlotType& slot, bool after = false)
     { return sigc::connection(connect_notify_(slot, after)); }
 };