"blah () isn't documnted", isn't that useful, since very little
of GObject is documented, and we know that.

But keeping open and retitling since you mention some details that 
definitely should be documented and could be overlooked.

I have added a note to g_signal_new() docs now - don't know the exact
reason though. I also notice in the implementation that it is not a
simple s/-/_/, but rather s/[_-|> <.:^]/_/. Should anything be said
about the other chars ? Final note: g_signal_lookup doesn't transform
the name in any way. Doesn't that lead to confusing behaviour where
you first register a signal with g_signal_new("my-signal",...) and
then g_signal_lookup("my-signal") comes up empty ?

As you've noted in bug 100119, registering my-signal will
result in entries being added for both my_signal and my-signal
to the table that g_signal_lookup() uses. 

I believe the intended behavior could be described as:

 A signal name consists of segments consisting of 
 ascii letters and digits, separated by either the
 '-' or '_' character. When registering a signal and
 lookup  a signal, either separator can be used, but 
 they cannot be mixed. (That is, 'foo-bar-baz' and
 'foo_bar_baz' refer to the same signal, but
 'foo-bar_baz' is illegal.)

Of course, the actual rules for registration are
looser than this:

 - The segments can consist of any sequence of bytes
   except for -_|> <.:^\0

 - Any byte other than \0 is treated as a segment
   separator.

But I think we can simply leave this under the 
rubric of "undefined behavior". The only questions
in my mind are:

 - What are the exact set of segment characters we
   should consider valid? The printing ASCII 
   characters currently allowed other than A-Za-z0-9 
   are ~`!@#$%&*()+=\]}[{'";,/?.  My instinct
   would be to simply disallow all of these, since they
   could cause a problem in one language or another.
   (And signal names are used as symbols in quite
   a few language bindings.) Use of non-ASCII characters
   should definitely not be allowed (unless we want
   to require valid UTF-8, but...)

 - Do we want to impose additional rules (In particular,   
   require that the first character of the signal name is 
   a segment separatoror [A-Za-z], so that signal names
   always have a valid representation as a C or C++ signal.)

 - Should we actually do validation of signal names to
   our documented rules in g_signal_new(), or just document
   the rules? I'd tend to not do so, at least until Glib-3.0.

 - What about property names?

I think allowing only a-zA-Z0-9 in segments and details is a good idea,
even if we don't enforce this yet. The docs should warn about
undefined behaviour if other characters are used. Demanding that
signal names start with a-zA-Z also seems good.

I think property names should follow the same rules. 

Ok to add a paragraph explaining this to the GSignal docs ?

Probably best to mail gtk-devel-list (maybe Cc timj@gtk.org)
first; if you don't get any response, then go ahead and
make the docs change. 

(One thing to be noted is that when using property names,
the '-' form is going to be considerably more efficient,
and in fact, for property names as details, you _have_
to use the '-' form.)

*** Bug 100119 has been marked as a duplicate of this bug. ***

Committed the signal name explanation now, keeping the bug open as a
reminder to add the same for parameter names.

Also added a note on property names now.