[glib] gsignal: Mention handler ID type in signal connection macro docs

[Philip Withnall <pwithnall src gnome org>]

commit 9f4d5e8b9176383f7063f235c23f9311cb412f07
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 10 16:12:41 2016 +0000

    gsignal: Mention handler ID type in signal connection macro docs
    
    gtk-doc doesn’t make the return type clear, because these are macros
    rather than inline functions, so people often have to guess at the
    return type (or look it up from g_signal_connect_closure(), but that’s
    hard work).
    
    Make it clear that the return type for handler IDs is gulong. While
    there, fix the capitalisation of ‘id’ to ‘ID’ in a few places.

 gobject/gsignal.c |   10 +++++-----
 gobject/gsignal.h |    6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)
---
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 26283e0..6cfefca 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -2312,7 +2312,7 @@ g_signal_get_invocation_hint (gpointer instance)
  *
  * Connects a closure to a signal for a particular object.
  *
- * Returns: the handler id (always greater than 0 for successful connections)
+ * Returns: the handler ID (always greater than 0 for successful connections)
  */
 gulong
 g_signal_connect_closure_by_id (gpointer  instance,
@@ -2371,7 +2371,7 @@ g_signal_connect_closure_by_id (gpointer  instance,
  *
  * Connects a closure to a signal for a particular object.
  *
- * Returns: the handler id (always greater than 0 for successful connections)
+ * Returns: the handler ID (always greater than 0 for successful connections)
  */
 gulong
 g_signal_connect_closure (gpointer     instance,
@@ -2464,7 +2464,7 @@ node_check_deprecated (const SignalNode *node)
  * used. Specify @connect_flags if you need `..._after()` or
  * `..._swapped()` variants of this function.
  *
- * Returns: the handler id (always greater than 0 for successful connections)
+ * Returns: the handler ID (always greater than 0 for successful connections)
  */
 gulong
 g_signal_connect_data (gpointer       instance,
@@ -2645,9 +2645,9 @@ g_signal_handler_disconnect (gpointer instance,
 /**
  * g_signal_handler_is_connected:
  * @instance: (type GObject.Object): The instance where a signal handler is sought.
- * @handler_id: the handler id.
+ * @handler_id: the handler ID.
  *
- * Returns whether @handler_id is the id of a handler connected to @instance.
+ * Returns whether @handler_id is the ID of a handler connected to @instance.
  *
  * Returns: whether @handler_id identifies a handler connected to @instance.
  */
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index c699fdf..42d4904 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -469,7 +469,7 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * See [memory management of signal handlers][signal-memory-management] for
  * details on how to handle the return value and memory management of @data.
  * 
- * Returns: the handler id (always greater than 0 for successful connections)
+ * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections)
  */
 #define g_signal_connect(instance, detailed_signal, c_handler, data) \
     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0)
@@ -484,7 +484,7 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * 
  * The handler will be called after the default handler of the signal.
  * 
- * Returns: the handler id (always greater than 0 for successful connections)
+ * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections)
  */
 #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \
     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER)
@@ -522,7 +522,7 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  *                   (GCallback) button_clicked_cb, other_widget);
  * ]|
  * 
- * Returns: the handler ID (always greater than 0 for successful connections)
+ * Returns: the handler ID, of type #gulong (always greater than 0 for successful connections)
  */
 #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \
     g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)