GSignal documentation

[Joshua N Pritikin <vishnu pobox com>]

After a few weeks of working with signals, i'm beginning to understand
how they work -- very cool.  However, i feel the documentation is
misleading or something.  The confusion arises here:

 guint       g_signal_newc                   (const gchar *signal_name,
                                              GType itype,
                                              GSignalFlags signal_flags,
                                              guint class_offset,
                                              GSignalAccumulator accumulator,
                                              gpointer accu_data,
                                              GSignalCMarshaller c_marshaller,
                                              GType return_type,
                                              guint n_params,
                                              ...);

Now, most of this is good stuff and self explanatory.  However, the
naming of `itype' is a mystery.  Instead of the generic term `itype',
the parameter name should be suggestive of the signal's subscription
scope or subscription granularity.  Perhaps `scope_type' is better.
The same misconception can be seen in the g_signal_connect_* prototype:

 gulong      g_signal_connect_data           (gpointer instance,
                                              const gchar *detailed_signal,
                                              GCallback c_handler,
                                              gpointer data,
                                              GClosureNotify destroy_data,
                                              gboolean swapped,
                                              gboolean after);

Everything is fine, except that the name `instance' is too generic.  It's
really a `scope_instance' -- since everything that connects to a signal's
scope receives emissions.  Contrary to the documentation, i feel like the
signal system doesn't have much to do with objects.  Rather it bridges
scopes and pierces abstraction layers -- i think of it as a run-time
scope system.

-- 
Get self-realization at <http://sahajayoga.org> ... <http://why-compete.org> ?
  Victory to the Divine Mother!!