[glib/wip/chergert/marshall-matters: 80/84] gsignal: update documentation about va_marshaller

[Christian Hergert <chergert src gnome org>]

commit 266a292a35f835746160b5f52529a2f7fec0686d
Author: Christian Hergert <chergert redhat com>
Date:   Thu May 30 18:41:02 2019 -0700

    gsignal: update documentation about va_marshaller
    
    If we specify a c_marshaller, g_signal_newv() will never assign an
    va_marshaller automatically. So either use NULL (for simple cases), or
    specify both to avoid the generic performance penalty.

 gobject/gsignal.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
---
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 551780327..26fba477f 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -1410,8 +1410,14 @@ g_signal_query (guint         signal_id,
  * in their class_init method by doing super_class->signal_handler = my_signal_handler.
  * Instead they will have to use g_signal_override_class_handler().
  *
- * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
- * the marshaller for this signal.
+ * If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
+ * the marshaller for this signal. In some simple cases, g_signal_new()
+ * will use a more optimized c_marshaller and va_marshaller for the signal
+ * instead of g_cclosure_marshal_generic().
+ *
+ * If @c_marshaller is non-%NULL, you need to also specify a va_marshaller
+ * using g_signal_set_va_marshaller() or the generic va_marshaller will
+ * be used.
  *
  * Returns: the signal id
  */