From 43a4bf8b038c08d6b8c565495cbf69433bc2dcc6 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 31 May 2011 16:15:43 +0100
Subject: Tidy up docs for DBusGMessage

* document the instance struct
* make argument names match the headers
* document the GType macro, not the function it calls, and mention it
  in the documentation (since this is a boxed type, so it's non-obvious)

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Cosimo Alfarano <cosimo.alfarano@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=37793
Bug-NB: related to NB#218973
---
 dbus/dbus-glib.c                     | 28 ++++++++++++++++++----------
 doc/reference/dbus-glib-sections.txt |  2 +-
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/dbus/dbus-glib.c b/dbus/dbus-glib.c
index 51f5141..3b32beb 100644
--- a/dbus/dbus-glib.c
+++ b/dbus/dbus-glib.c
@@ -98,39 +98,46 @@ dbus_g_connection_unref (DBusGConnection *connection)
  * @see_also: #DBusMessage
  * @stability: Stable
  *
- * A #DBusGConnection is a boxed type abstracting a DBusMessage.
+ * A #DBusGMessage is a boxed type abstracting a DBusMessage.
+ */
+
+/**
+ * DBusGMessage:
+ *
+ * A #DBusGMessage is a boxed type abstracting a DBusMessage from
+ * libdbus.
  */
 
 /**
  * dbus_g_message_ref:
- * @gmessage: the message to ref
+ * @message: the message to ref
  *
  * Increment refcount on a #DBusGMessage
  * 
  * Returns: the message that was ref'd
  */
 DBusGMessage*
-dbus_g_message_ref (DBusGMessage *gmessage)
+dbus_g_message_ref (DBusGMessage *message)
 {
   DBusMessage *c;
 
-  c = DBUS_MESSAGE_FROM_G_MESSAGE (gmessage);
+  c = DBUS_MESSAGE_FROM_G_MESSAGE (message);
   dbus_message_ref (c);
-  return gmessage;
+  return message;
 }
 
 /**
  * dbus_g_message_unref:
- * @gmessage: the message to unref
+ * @message: the message to unref
  * 
  * Decrement refcount on a #DBusGMessage
  */
 void
-dbus_g_message_unref (DBusGMessage *gmessage)
+dbus_g_message_unref (DBusGMessage *message)
 {
   DBusMessage *c;
 
-  c = DBUS_MESSAGE_FROM_G_MESSAGE (gmessage);
+  c = DBUS_MESSAGE_FROM_G_MESSAGE (message);
   dbus_message_unref (c);
 }
 
@@ -270,8 +277,9 @@ dbus_g_connection_get_g_type (void)
 }
 
 /**
- * dbus_g_message_get_g_type:
- * Get the GLib type ID for a #DBusGMessage boxed type.
+ * DBUS_TYPE_G_MESSAGE:
+ *
+ * Expands to a function call returning the boxed #GType of a #DBusGConnection.
  *
  * Returns: the GLib type
  */
diff --git a/doc/reference/dbus-glib-sections.txt b/doc/reference/dbus-glib-sections.txt
index 25c02b7..8aa31b4 100644
--- a/doc/reference/dbus-glib-sections.txt
+++ b/doc/reference/dbus-glib-sections.txt
@@ -37,11 +37,11 @@ dbus_glib_global_set_disable_legacy_property_access
 <TITLE>DBusGMessage</TITLE>
 <INCLUDE>dbus/dbus-glib.h</INCLUDE>
 DBusGMessage
+DBUS_TYPE_G_MESSAGE
 dbus_g_message_ref
 dbus_g_message_unref
 dbus_g_message_get_message
 <SUBSECTION Standard>
-DBUS_TYPE_G_MESSAGE
 dbus_g_message_get_g_type
 </SECTION>
 
-- 
cgit v1.2.3