add docs for EggDBusMethodInvocation and add _valist() variants

3 files changed, 121 insertions, 20 deletions

diff --git a/docs/eggdbus/eggdbus-sections.txt b/docs/eggdbus/eggdbus-sections.txt
index 5ccaff9..1bde1f7 100644
--- a/docs/eggdbus/eggdbus-sections.txt
+++ b/docs/eggdbus/eggdbus-sections.txt
@@ -443,9 +443,11 @@ egg_dbus_method_invocation_create_reply_message
 egg_dbus_method_invocation_get_connection
 egg_dbus_method_invocation_add_destroy_notify
 egg_dbus_method_invocation_return_error
+egg_dbus_method_invocation_return_error_valist
 egg_dbus_method_invocation_return_error_literal
 egg_dbus_method_invocation_return_gerror
 egg_dbus_method_invocation_return_dbus_error
+egg_dbus_method_invocation_return_dbus_error_valist
 egg_dbus_method_invocation_return_dbus_error_literal
 <SUBSECTION Standard>
 EGG_DBUS_METHOD_INVOCATION
diff --git a/src/eggdbus/eggdbusmethodinvocation.c b/src/eggdbus/eggdbusmethodinvocation.c
index 9e290c8..63b6dea 100644
--- a/src/eggdbus/eggdbusmethodinvocation.c
+++ b/src/eggdbus/eggdbusmethodinvocation.c
@@ -28,6 +28,16 @@
 #include <eggdbus/eggdbusconnection.h>
 #include <eggdbus/eggdbusprivate.h>
 
+/**
+ * SECTION:eggdbusmethodinvocation
+ * @title: EggDBusMethodInvocation
+ * @short_description: Handling remote method calls
+ *
+ * Instances of the #EggDBusMethodInvocation class are used when handling D-Bus method calls. It
+ * provides a way to get information (such as the UNIX process identifier if applicable) about
+ * the remote end invoking the method. It also provides a mechanism to return errors.
+ */
+
 typedef struct
 {
   EggDBusMessage *request_message;
@@ -100,6 +110,16 @@ egg_dbus_method_invocation_class_init (EggDBusMethodInvocationClass *klass)
   g_type_class_add_private (klass, sizeof (EggDBusMethodInvocationPrivate));
 }
 
+/**
+ * egg_dbus_method_invocation_new:
+ * @request_message: The message encapsulating the method call request.
+ * @source_tag: An user provided tag.
+ *
+ * Creates a new #EggDBusMethodInvocation. This method is only useful for
+ * language bindings.
+ *
+ * Returns: A #EggDBusMethodInvocation. Free with g_object_unref().
+ **/
 EggDBusMethodInvocation *
 egg_dbus_method_invocation_new (EggDBusMessage         *request_message,
                                 gpointer                source_tag)
@@ -118,6 +138,15 @@ egg_dbus_method_invocation_new (EggDBusMessage         *request_message,
   return method_invocation;
 }
 
+/**
+ * egg_dbus_method_invocation_get_source_tag:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ *
+ * Gets the user provided tag for @method_invocation. This method is only useful for
+ * language bindings.
+ *
+ * Returns: The user provided tag set when @method_invocation was constructed.
+ **/
 gpointer
 egg_dbus_method_invocation_get_source_tag (EggDBusMethodInvocation *method_invocation)
 {
@@ -128,6 +157,16 @@ egg_dbus_method_invocation_get_source_tag (EggDBusMethodInvocation *method_invoc
   return priv->source_tag;
 }
 
+/**
+ * egg_dbus_method_invocation_create_reply_message:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ *
+ * Creates a #EggDBusMessage in reply to the #EggDBusMessage passed when
+ * @method_invocation was created. This method is only useful for
+ * language bindings.
+ *
+ * Returns: A new #EggDBusMessage. Free with g_object_unref().
+ **/
 EggDBusMessage *
 egg_dbus_method_invocation_create_reply_message (EggDBusMethodInvocation *method_invocation)
 {
@@ -141,6 +180,14 @@ egg_dbus_method_invocation_create_reply_message (EggDBusMethodInvocation *method
   return reply;
 }
 
+/**
+ * egg_dbus_method_invocation_get_connection:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ *
+ * Gets the #EggDBusConnection that @method_invocation is associated with.
+ *
+ * Returns: A #EggDBusConnection. Do not free, the returned object is owned by @method_invocation.
+ **/
 EggDBusConnection *
 egg_dbus_method_invocation_get_connection (EggDBusMethodInvocation *method_invocation)
 {
@@ -154,10 +201,10 @@ egg_dbus_method_invocation_get_connection (EggDBusMethodInvocation *method_invoc
 /**
  * egg_dbus_method_invocation_add_destroy_notify:
  * @method_invocation: A #EggDBusMethodInvocation.
- * @data: data to free.
- * @func: free function.
+ * @data: Data to free.
+ * @func: Free function.
  *
- * Makes @method_invocation call @func with a a single parameters,
+ * Makes @method_invocation call @func with a a single parameter,
  * @data, upon finalization.
  **/
 void
@@ -175,7 +222,18 @@ egg_dbus_method_invocation_add_destroy_notify (EggDBusMethodInvocation *method_i
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-static void
+/**
+ * egg_dbus_method_invocation_return_error_valist:
+ * egg_dbus_method_invocation_return_error:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ * @domain: Error domain.
+ * @code: Error code.
+ * @format: printf() style format for human readable message.
+ * @var_args: Arguments for @format.
+ *
+ * Like egg_dbus_method_invocation_return_error() but intended for language bindings.
+ **/
+void
 egg_dbus_method_invocation_return_error_valist (EggDBusMethodInvocation *method_invocation,
                                               GQuark                 domain,
                                               gint                   code,
@@ -198,20 +256,21 @@ egg_dbus_method_invocation_return_error_valist (EggDBusMethodInvocation *method_
  * @method_invocation: A #EggDBusMethodInvocation.
  * @domain: Error domain.
  * @code: Error code.
- * @format: <literal>printf()</literal>-style format.
- * @...: arguments for @format.
+ * @format: printf() style format for human readable message.
+ * @...: Arguments for @format.
+ *
+ * Use this to return an error when handling a D-Bus method call. The error will be propagated
+ * to the remote caller.
  *
- * Returns an error from a server implementation. The error will be
- * propagated to the remote caller. This completes the method
- * invocation and you don't have to call the corresponding
- * <literal>_finish()</literal> method.
+ * This completes the method invocation and you don't have to call the corresponding
+ * <literal>_finish()</literal> method in your D-Bus method call handler.
  **/
 void
 egg_dbus_method_invocation_return_error (EggDBusMethodInvocation *method_invocation,
-                                       GQuark                 domain,
-                                       gint                   code,
-                                       const gchar           *format,
-                                       ...)
+                                         GQuark                 domain,
+                                         gint                   code,
+                                         const gchar           *format,
+                                         ...)
 {
   va_list va_args;
 
@@ -229,10 +288,10 @@ egg_dbus_method_invocation_return_error (EggDBusMethodInvocation *method_invocat
  * @method_invocation: A #EggDBusMethodInvocation.
  * @domain: Error domain.
  * @code: Error code.
- * @message: error message
+ * @message: Human readable error message.
  *
  * Like egg_dbus_method_invocation_return_error() but without
- * <literal>printf()</literal>-style formatting.
+ * printf()-style formatting.
  **/
 void
 egg_dbus_method_invocation_return_error_literal (EggDBusMethodInvocation *method_invocation,
@@ -252,8 +311,7 @@ egg_dbus_method_invocation_return_error_literal (EggDBusMethodInvocation *method
  * @method_invocation: A #EggDBusMethodInvocation.
  * @error: A #GError.
  *
- * Like egg_dbus_method_invocation_return_error() but takes a
- * a #GError instead.
+ * Like egg_dbus_method_invocation_return_error() but takes a a #GError instead.
  **/
 void
 egg_dbus_method_invocation_return_gerror (EggDBusMethodInvocation *method_invocation,
@@ -273,7 +331,16 @@ egg_dbus_method_invocation_return_gerror (EggDBusMethodInvocation *method_invoca
   g_free (error_name);
 }
 
-static void
+/**
+ * egg_dbus_method_invocation_return_dbus_error_valist:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ * @name: A D-Bus error name such as <literal>org.freedesktop.DBus.Error.UnknownMethod</literal>.
+ * @format: printf() style format for human readable message.
+ * @var_args: Arguments for @format.
+ *
+ * Like egg_dbus_method_invocation_return_dbus_error() but intended for langauge bindings.
+ **/
+void
 egg_dbus_method_invocation_return_dbus_error_valist (EggDBusMethodInvocation *method_invocation,
                                                    const gchar           *name,
                                                    const gchar           *format,
@@ -290,6 +357,19 @@ egg_dbus_method_invocation_return_dbus_error_valist (EggDBusMethodInvocation *me
   g_free (literal_message);
 }
 
+/**
+ * egg_dbus_method_invocation_return_dbus_error:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ * @name: A D-Bus error name such as <literal>org.freedesktop.DBus.Error.UnknownMethod</literal>.
+ * @format: printf() style format for human readable message.
+ * @...: Arguments for @format.
+ *
+ * Use this to return a raw D-Bus error when handling a D-Bus method call. The error will
+ * be propagated to the remote caller.
+ *
+ * This completes the method invocation and you don't have to call the corresponding
+ * <literal>_finish()</literal> method in your D-Bus method call handler.
+ **/
 void
 egg_dbus_method_invocation_return_dbus_error (EggDBusMethodInvocation *method_invocation,
                                             const gchar           *name,
@@ -306,6 +386,15 @@ egg_dbus_method_invocation_return_dbus_error (EggDBusMethodInvocation *method_in
   va_end (va_args);
 }
 
+/**
+ * egg_dbus_method_invocation_return_dbus_error_literal:
+ * @method_invocation: A #EggDBusMethodInvocation.
+ * @name: A D-Bus error name such as <literal>org.freedesktop.DBus.Error.UnknownMethod</literal>.
+ * @message: Human readable message to pass.
+ *
+ * Like egg_dbus_method_invocation_return_dbus_error() but without
+ * printf()-style formatting.
+ **/
 void
 egg_dbus_method_invocation_return_dbus_error_literal (EggDBusMethodInvocation *method_invocation,
                                                     const gchar           *name,
@@ -324,4 +413,3 @@ egg_dbus_method_invocation_return_dbus_error_literal (EggDBusMethodInvocation *m
 
   g_object_unref (reply);
 }
-
diff --git a/src/eggdbus/eggdbusmethodinvocation.h b/src/eggdbus/eggdbusmethodinvocation.h
index dce7d6d..1b4e36e 100644
--- a/src/eggdbus/eggdbusmethodinvocation.h
+++ b/src/eggdbus/eggdbusmethodinvocation.h
@@ -81,6 +81,12 @@ void                   egg_dbus_method_invocation_return_error         (EggDBusM
                                                                         const gchar             *format,
                                                                         ...) G_GNUC_PRINTF (4, 5);
 
+void                   egg_dbus_method_invocation_return_error_valist  (EggDBusMethodInvocation *method_invocation,
+                                                                        GQuark                   domain,
+                                                                        gint                     code,
+                                                                        const gchar             *format,
+                                                                        va_list                  var_args);
+
 void                   egg_dbus_method_invocation_return_error_literal (EggDBusMethodInvocation *method_invocation,
                                                                         GQuark                   domain,
                                                                         gint                     code,
@@ -94,6 +100,11 @@ void                   egg_dbus_method_invocation_return_dbus_error    (EggDBusM
                                                                         const gchar             *format,
                                                                         ...) G_GNUC_PRINTF (3, 4);
 
+void                   egg_dbus_method_invocation_return_dbus_error_valist (EggDBusMethodInvocation *method_invocation,
+                                                                            const gchar             *name,
+                                                                            const gchar             *format,
+                                                                            va_list                  var_args);
+
 void                   egg_dbus_method_invocation_return_dbus_error_literal (EggDBusMethodInvocation *method_invocation,
                                                                              const gchar             *name,
                                                                              const gchar             *message);