Attachment 51673 Details for Bug 37793 – [1/6 v2] Tidy up docs for DBusGError and its pseudo-methods

[patch] [1/6 v2] Tidy up docs for DBusGError and its pseudo-methods

0001-Tidy-up-docs-for-DBusGError-and-its-pseudo-methods.patch (text/plain), 3.53 KB, created by Simon McVittie on 2011-09-27 11:02:29 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2011-09-27 11:02:29 UTC

Size: 3.53 KB

patch

obsolete

>From a291e3194db44b4382606f98000b090a6c261a7b Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Tue, 31 May 2011 16:17:10 +0100
>Subject: [PATCH 1/6] Tidy up docs for DBusGError and its pseudo-methods
>
>* attach the introductory doc-comments to the enum and macro names,
>  not the internal function
>* remove docs for method parameters which didn't actually exist
>* more cross-references
>* make the domain macro visible in the documentation index
>---
> dbus/dbus-glib.c                     |   33 ++++++++++++++++++---------------
> doc/reference/dbus-glib-sections.txt |    1 -
> 2 files changed, 18 insertions(+), 16 deletions(-)
>
>diff --git a/dbus/dbus-glib.c b/dbus/dbus-glib.c
>index f64903a..8813da6 100644
>--- a/dbus/dbus-glib.c
>+++ b/dbus/dbus-glib.c
>@@ -151,12 +151,18 @@ dbus_g_message_unref (DBusGMessage *message)
>  */
> 
> /**
>- * dbus_g_error_quark:
>+ * DBusGError:
>  *
>- * The implementation of #DBUS_GERROR error domain. See documentation
>- * for #GError in GLib reference manual.
>+ * A #GError enumeration for the domain %DBUS_GERROR. The values' meanings
>+ * can be found by looking at the comments for the corresponding constants
>+ * in dbus-protocol.h.
>+ */
>+
>+/**
>+ * DBUS_GERROR:
>  *
>- * Returns: the error domain quark for use with #GError
>+ * Expands to a function call returning the error domain quark for #DBusGError,
>+ * for use with #GError.
>  */
> GQuark
> dbus_g_error_quark (void)
>@@ -171,17 +177,16 @@ dbus_g_error_quark (void)
>  * dbus_g_error_has_name:
>  * @error: the GError given from the remote method
>  * @name: the D-BUS error name
>- * @msg: the D-BUS error detailed message
>  *
>  * Determine whether D-BUS error name for a remote exception matches
>  * the given name.  This function is intended to be invoked on a
>- * GError returned from an invocation of a remote method, e.g. via
>- * dbus_g_proxy_end_call.  It will silently return FALSE for errors
>+ * #GError returned from an invocation of a remote method, e.g. via
>+ * dbus_g_proxy_end_call().  It will silently return %FALSE for errors
>  * which are not remote D-BUS exceptions (i.e. with a domain other
>- * than DBUS_GERROR or a code other than
>- * DBUS_GERROR_REMOTE_EXCEPTION).
>+ * than %DBUS_GERROR or a code other than
>+ * %DBUS_GERROR_REMOTE_EXCEPTION).
>  *
>- * Returns: TRUE iff the remote error has the given name
>+ * Returns: %TRUE if and only if the remote error has the given name
>  */
> gboolean
> dbus_g_error_has_name (GError *error, const char *name)
>@@ -198,13 +203,11 @@ dbus_g_error_has_name (GError *error, const char *name)
> /**
>  * dbus_g_error_get_name:
>  * @error: the #GError given from the remote method
>- * @name: the D-BUS error name
>- * @msg: the D-BUS error detailed message
>  *
>  * This function may only be invoked on a #GError returned from an
>- * invocation of a remote method, e.g. via dbus_g_proxy_end_call.
>- * Moreover, you must ensure that the error's domain is #DBUS_GERROR,
>- * and the code is #DBUS_GERROR_REMOTE_EXCEPTION.
>+ * invocation of a remote method, e.g. via dbus_g_proxy_end_call().
>+ * Moreover, you must ensure that the error's domain is %DBUS_GERROR,
>+ * and the code is %DBUS_GERROR_REMOTE_EXCEPTION.
>  *
>  * Returns: the D-BUS name for a remote exception.
>  */
>diff --git a/doc/reference/dbus-glib-sections.txt b/doc/reference/dbus-glib-sections.txt
>index a9786b4..cbf1226 100644
>--- a/doc/reference/dbus-glib-sections.txt
>+++ b/doc/reference/dbus-glib-sections.txt
>@@ -67,7 +67,6 @@ dbus_g_error_has_name
> dbus_g_error_get_name
> dbus_g_error_quark
> dbus_g_error_domain_register
>-<SUBSECTION Standard>
> DBUS_GERROR
> </SECTION>
> 
>-- 
>1.7.6.3
>

Actions: View | Splinter Review

Attachments on bug 37793: 47383 | 47384 | 47385 | 47386 | 47387 | 47388 | 47389 | 47390 | 47391 | 47392 | 47393 | 47394 | 47395 | 47396 | 51673 | 51674 | 51676 | 51677 | 51679 | 51680

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.