From 620b8bbfb76f54070ce45f9de5af7b2a5a111086 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 27 Sep 2011 18:42:33 +0100 Subject: [PATCH 6/6] Fix various minor documentation bugs --- dbus/dbus-glib.c | 2 +- dbus/dbus-glib.h | 2 +- dbus/dbus-gmain.c | 10 +++++----- dbus/dbus-gobject.c | 33 +++++++++++++++++++-------------- dbus/dbus-gproxy.c | 33 ++++++++++++++++++++++++++++----- dbus/dbus-gvalue.c | 2 +- doc/reference/dbus-glib-sections.txt | 6 +++++- 7 files changed, 60 insertions(+), 28 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) diff --git a/doc/reference/dbus-glib-sections.txt b/doc/reference/dbus-glib-sections.txt index 0c18675..90015c3 100644 --- a/doc/reference/dbus-glib-sections.txt +++ b/doc/reference/dbus-glib-sections.txt @@ -65,9 +65,10 @@ dbus_g_method_return_error DBusGError dbus_g_error_has_name dbus_g_error_get_name -dbus_g_error_quark dbus_g_error_domain_register DBUS_GERROR + +dbus_g_error_quark
@@ -122,6 +123,8 @@ DBUS_TYPE_MESSAGE dbus_connection_get_g_type dbus_message_get_g_type + +DBUS_INSIDE_DBUS_GLIB_H
@@ -192,5 +195,6 @@ DBUS_TYPE_G_SIGNATURE DBusGObjectPath DBUS_TYPE_G_OBJECT_PATH +dbus_g_object_path_get_g_type dbus_g_signature_get_g_type
-- 1.7.6.3