Fix various minor documentation bugsHEADmaster

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

6 files changed, 55 insertions, 27 deletions

diff --git a/dbus/dbus-glib.c b/dbus/dbus-glib.c
index 8813da6..4ca8db6 100644
--- a/dbus/dbus-glib.c
+++ b/dbus/dbus-glib.c
@@ -372,7 +372,7 @@ dbus_g_message_get_message (DBusGMessage *gmessage)
 
 /*
  * Unit test for general glib stuff
- * Returns: #TRUE on success.
+ * Returns: %TRUE on success.
  */
 gboolean
 _dbus_glib_test (const char *test_data_dir)
diff --git a/dbus/dbus-glib.h b/dbus/dbus-glib.h
index 1bbc284..9a2076f 100644
--- a/dbus/dbus-glib.h
+++ b/dbus/dbus-glib.h
@@ -159,7 +159,7 @@ void       dbus_glib_global_set_disable_legacy_property_access (void);
 void       dbus_g_object_type_install_info     (GType                 object_type,
                                                 const DBusGObjectInfo *info);
 
-void       dbus_g_object_type_register_shadow_property (GType         object_type,
+void       dbus_g_object_type_register_shadow_property (GType         iface_type,
                                                         const char    *dbus_prop_name,
                                                         const char    *shadow_prop_name);
 
diff --git a/dbus/dbus-gmain.c b/dbus/dbus-gmain.c
index caca03b..6cf5af5 100644
--- a/dbus/dbus-gmain.c
+++ b/dbus/dbus-gmain.c
@@ -516,11 +516,11 @@ connection_setup_new_from_old (GMainContext    *context,
 /**
  * dbus_connection_setup_with_g_main:
  * @connection: the connection
- * @context: the #GMainContext or #NULL for default context
+ * @context: the #GMainContext or %NULL for default context
  *
  * Sets the watch and timeout functions of a #DBusConnection
  * to integrate the connection with the GLib main loop.
- * Pass in #NULL for the #GMainContext unless you're
+ * Pass in %NULL for the #GMainContext unless you're
  * doing something specialized.
  *
  * If called twice for the same context, does nothing the second
@@ -594,11 +594,11 @@ dbus_connection_setup_with_g_main (DBusConnection *connection,
 /**
  * dbus_server_setup_with_g_main:
  * @server: the server
- * @context: the #GMainContext or #NULL for default
+ * @context: the #GMainContext or %NULL for default
  *
  * Sets the watch and timeout functions of a #DBusServer
  * to integrate the server with the GLib main loop.
- * In most cases the context argument should be #NULL.
+ * In most cases the context argument should be %NULL.
  *
  * If called twice for the same context, does nothing the second
  * time. If called once with context A and once with context B,
@@ -791,7 +791,7 @@ dbus_g_bus_get_private (DBusBusType     type,
 
 /*
  * Unit test for GLib main loop integration
- * Returns: #TRUE on success.
+ * Returns: %TRUE on success.
  */
 gboolean
 _dbus_gmain_test (const char *test_data_dir)
diff --git a/dbus/dbus-gobject.c b/dbus/dbus-gobject.c
index 1a82c42..bda4def 100644
--- a/dbus/dbus-gobject.c
+++ b/dbus/dbus-gobject.c
@@ -1637,6 +1637,8 @@ gerror_to_dbus_error_message (const DBusGObjectInfo *object_info,
  */
 
 /**
+ * DBusGMethodInvocation:
+ *
  * The context of an asynchronous method call.  See dbus_g_method_return() and
  * dbus_g_method_return_error().
  */
@@ -2041,7 +2043,7 @@ done:
  * Check that the requested property exists and the requested access is
  * allowed. If not, reply with a D-Bus AccessDenied error message.
  *
- * Returns: %TRUE if property access can continue, or FALSE if an error
+ * Returns: %TRUE if property access can continue, or %FALSE if an error
  *    reply has been sent
  */
 static gboolean
@@ -2518,7 +2520,7 @@ dbus_error_to_gerror_code (const char *derr)
 /**
  * dbus_set_g_error:
  * @gerror: an error
- * @error: a #DBusError
+ * @derror: a #DBusError
  *
  * Store the information from a DBus method error return into a
  * GError.  For the normal case of an arbitrary remote process,
@@ -2539,27 +2541,27 @@ dbus_error_to_gerror_code (const char *derr)
  */
 void
 dbus_set_g_error (GError    **gerror,
-		  DBusError  *error)
+                  DBusError  *derror)
 {
   int code;
 
-  g_return_if_fail (error != NULL);
-  g_return_if_fail (dbus_error_is_set (error));
+  g_return_if_fail (derror != NULL);
+  g_return_if_fail (dbus_error_is_set (derror));
   g_return_if_fail (gerror == NULL || *gerror == NULL);
 
-  code = dbus_error_to_gerror_code (error->name);
+  code = dbus_error_to_gerror_code (derror->name);
   if (code != DBUS_GERROR_REMOTE_EXCEPTION)
     g_set_error (gerror, DBUS_GERROR,
 		 code,
 		 "%s",
-		 error->message);
+		 derror->message);
   else
     g_set_error (gerror, DBUS_GERROR,
 		 code,
 		 "%s%c%s",
-		 error->message ? error->message : "",
+		 derror->message ? derror->message : "",
 		 '\0',
-		 error->name);
+		 derror->name);
 }
 
 static void
@@ -2616,7 +2618,7 @@ dbus_glib_global_set_disable_legacy_property_access (void)
  * class_init() for the object class.
  *
  * Once introspection information has been installed, instances of the
- * object registered with #dbus_g_connection_register_g_object() can have
+ * object registered with dbus_g_connection_register_g_object() can have
  * their methods invoked remotely.
  */
 void
@@ -3030,7 +3032,7 @@ _dbus_gobject_lookup_marshaller (GType        rettype,
  * dbus_g_object_register_marshaller:
  * @marshaller: a GClosureMarshal to be used for invocation
  * @rettype: a GType for the return type of the function
- * @:... The parameter #GTypes, followed by %G_TYPE_INVALID
+ * @...: The parameter #GTypes, followed by %G_TYPE_INVALID
  *
  * Register a #GClosureMarshal to be used for signal invocations,
  * giving its return type and a list of parameter types,
@@ -3069,7 +3071,7 @@ dbus_g_object_register_marshaller (GClosureMarshal  marshaller,
  * @types: a C array of GTypes values
  *
  * Register a #GClosureMarshal to be used for signal invocations.
- * @see_also #dbus_g_object_register_marshaller
+ * @see_also dbus_g_object_register_marshaller()
  */
 void
 dbus_g_object_register_marshaller_array (GClosureMarshal  marshaller,
@@ -3142,10 +3144,11 @@ dbus_g_method_get_reply (DBusGMethodInvocation *context)
 
 /**
  * dbus_g_method_send_reply:
- * Send a manually created reply message
  * @context: the method context
  * @reply: the reply message, will be unreffed
  *
+ * Send a manually created reply message.
+ *
  * Used as a sidedoor when you can't generate dbus values
  * of the correct type due to glib binding limitations
  */
@@ -3168,6 +3171,8 @@ dbus_g_method_send_reply (DBusGMethodInvocation *context, DBusMessage *reply)
 /**
  * dbus_g_method_return:
  * @context: the method context
+ * @...: zero or more values to return from the method, with their number
+ *    and types given by its #DBusGObjectInfo
  *
  * Send a return message for a given method invocation, with arguments.
  * This function also frees the sending context.
@@ -3336,7 +3341,7 @@ const DBusGObjectInfo dbus_glib_internal_test_object_info = {
 
 /*
  * Unit test for GLib GObject integration ("skeletons")
- * Returns: #TRUE on success.
+ * Returns: %TRUE on success.
  */
 gboolean
 _dbus_gobject_test (const char *test_data_dir)
diff --git a/dbus/dbus-gproxy.c b/dbus/dbus-gproxy.c
index 6af93ba..16ee119 100644
--- a/dbus/dbus-gproxy.c
+++ b/dbus/dbus-gproxy.c
@@ -1806,6 +1806,17 @@ dbus_g_proxy_emit_remote_signal (DBusGProxy  *proxy,
   goto out;
 }
 
+/**
+ * DBusGProxyCallNotify:
+ * @proxy: the proxy on which the method was called
+ * @call_id: the call in progress
+ * @user_data: data passed to dbus_g_proxy_begin_call() or similar
+ *
+ * Called when a reply to the call represented by @call_id arrives.
+ * Use dbus_g_proxy_end_call() to see whether @call_id succeeded or
+ * failed, and get the arguments returned (if any) on success.
+ */
+
 typedef struct
 {
   DBusGProxy *proxy;
@@ -1921,6 +1932,18 @@ manager_begin_bus_call (DBusGProxyManager    *manager,
  * service.
  */
 
+/**
+ * DBusGProxy:
+ *
+ * A #GObject representing a remote object in a D-Bus service.
+ */
+
+/**
+ * DBusGProxyCall:
+ *
+ * An opaque pointer representing an asynchronous call in progress.
+ */
+
 /*
  * dbus_g_proxy_get_type:
  * Standard GObject get_type() function for DBusGProxy.
@@ -2039,7 +2062,7 @@ dbus_g_proxy_new_for_name (DBusGConnection *connection,
  * dbus_g_proxy_new_for_name_owner() will bind to the unique name
  * of that owner rather than the generic name.
  * 
- * Returns: new proxy object, or #NULL on error
+ * Returns: new proxy object, or %NULL on error
  */
 DBusGProxy*
 dbus_g_proxy_new_for_name_owner (DBusGConnection          *connection,
@@ -2133,12 +2156,12 @@ dbus_g_proxy_new_for_peer (DBusGConnection          *connection,
  * dbus_g_proxy_get_bus_name:
  * @proxy: the proxy
  *
- * Gets the bus name a proxy is bound to (may be #NULL in some cases).
+ * Gets the bus name a proxy is bound to (may be %NULL in some cases).
  * If you created the proxy with dbus_g_proxy_new_for_name(), then
  * the name you passed to that will be returned.
  * If you created it with dbus_g_proxy_new_for_name_owner(), then the
  * unique connection name will be returned. If you created it
- * with dbus_g_proxy_new_for_peer() then #NULL will be returned.
+ * with dbus_g_proxy_new_for_peer() then %NULL will be returned.
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
@@ -2162,7 +2185,7 @@ dbus_g_proxy_get_bus_name (DBusGProxy        *proxy)
  * dbus_g_proxy_get_interface:
  * @proxy: the proxy
  *
- * Gets the object interface proxy is bound to (may be #NULL in some cases).
+ * Gets the object interface proxy is bound to (may be %NULL in some cases).
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
@@ -2910,7 +2933,7 @@ dbus_g_proxy_cancel_call (DBusGProxy        *proxy,
  * dbus_g_proxy_send:
  * @proxy: a proxy for a remote interface
  * @message: the message to address and send
- * @client_serial: return location for message's serial, or #NULL 
+ * @client_serial: return location for message's serial, or %NULL
  *
  * Sends a message to the interface we're proxying for.  Does not
  * block or wait for a reply. The message is only actually written out
diff --git a/dbus/dbus-gvalue.c b/dbus/dbus-gvalue.c
index a9cae0c..5c13c58 100644
--- a/dbus/dbus-gvalue.c
+++ b/dbus/dbus-gvalue.c
@@ -2027,7 +2027,7 @@ assert_bidirectional_mapping (GType gtype, const char *expected_sig)
 
 /*
  * Unit test for general glib stuff
- * Returns: #TRUE on success.
+ * Returns: %TRUE on success.
  */
 gboolean
 _dbus_gvalue_test (const char *test_data_dir)