[glib: 7/19] gsignal: Tidy up signal naming documentation

[Emmanuele Bassi <ebassi src gnome org>]

commit b8eb6025f1ea1d92b94f21ec2e6f45c64782acb0
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Nov 12 19:35:19 2019 +0000

    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

 gobject/gsignal.c | 8 +++++---
 1 file 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.