gsignal: Tidy up signal naming documentation

Since signal names are the same as property names, reference between the
two. Improve the formatting, and make it clearer that `_` is
discouraged.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Helps: #358

1 files changed, 5 insertions, 3 deletions

diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 76f889384..4a8996db1 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -1403,12 +1403,14 @@ g_signal_query (guint         signal_id,
  * Creates a new signal. (This is usually done in the class initializer.)
  *
  * A signal name consists of segments consisting of ASCII letters and
- * digits, separated by either the '-' or '_' character. The first
+ * digits, separated by either the `-` or `_` character. The first
  * character of a signal name must be a letter. Names which violate these
- * rules lead to undefined behaviour of the GSignal system.
+ * rules lead to undefined behaviour. These are the same rules as for property
+ * naming (see g_param_spec_internal()).
  *
  * When registering a signal and looking up a signal, either separator can
- * be used, but they cannot be mixed.
+ * be used, but they cannot be mixed. Using `-` is considerably more efficient.
+ * Using `_` is discouraged.
  *
  * If 0 is used for @class_offset subclasses cannot override the class handler
  * in their class_init method by doing super_class->signal_handler = my_signal_handler.