[glib/wip/chergert/marshall-matters: 1/3] gsignal: update documentation about va_marshaller

[Philip Withnall <pwithnall src gnome org>]

commit 966df9cb68664907feb4bfe393c377e0e13635c6
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.
    
    Helps: #1532

 gobject/gsignal.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
---
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 551780327..3e6ac7b82 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
  */