[gupnp/wip/phako/cleanup: 21/21] wip: more docs

[Jens Georg <jensgeorg src gnome org>]

commit 4ec09329956a539e988b2c83a4ba0483db33a2f2
Author: Jens Georg <mail jensge org>
Date:   Sun May 30 23:17:38 2021 +0200

    wip: more docs

 libgupnp/gupnp-service-proxy-action.c | 87 +++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
---
diff --git a/libgupnp/gupnp-service-proxy-action.c b/libgupnp/gupnp-service-proxy-action.c
index c40689c..6959928 100644
--- a/libgupnp/gupnp-service-proxy-action.c
+++ b/libgupnp/gupnp-service-proxy-action.c
@@ -277,6 +277,54 @@ write_footer (GUPnPServiceProxyAction *action)
                          "</s:Envelope>");
 }
 
+/**
+ * gupnp_service_proxy_action_new:
+ * @action: The name of a remote action to call
+ * @...: tuples of in parameter name, in parameter type, and in parameter
+ * value, terminated with %NULL
+ *
+ * Prepares action @action with parameters @Varargs to be sent off to
+ * a remote service later with gupnp_service_proxy_call_action() or
+ * gupnp_service_proxy_call_action_async().
+ *
+ * After the action call has finished, the results of the call may be
+ * retrived from the #GUPnPServiceProxyAction by using
+ * gupnp_service_proxy_action_get_result(),
+ * gupnp_service_proxy_action_get_result_list() or
+ * gupnp_service_proxy_action_get_result_hash()
+ *
+ * <informalexample>
+ * <programlisting>
+ * GUPnPServiceProxyAction *action =
+ *         gupnp_service_proxy_action_new ("GetVolume",
+ *                                         // Parameters
+ *                                         "InstanceID", G_TYPE_INT, 0,
+ *                                         "Channel", G_TYPE_STRING, "Master",
+ *                                         NULL);
+ *
+ * GError *error = NULL;
+ * gupnp_service_proxy_call_action (proxy, action, NULL, &error);
+ * if (error != NULL) {
+ *         g_warning ("Failed to call GetVolume: %s", error->message);
+ *         g_clear_error (&error);
+ *
+ *         return;
+ * }
+ *
+ * guint16 volume = 0;
+ * if (!gupnp_service_proxy_action_get_result (action,
+ *                                             &error,
+ *                                             "CurrentVolume", G_TYPE_UINT, &volume,
+ *                                             NULL)) {
+ *         g_message ("Current Volume: %u", volume);
+ * }
+ *
+ * gupnp_service_proxy_action_unref (action);
+ * </programlisting>
+ * </informalexample>
+ *
+ * Returns: A newly created #GUPnPServiceProxyAction
+ */
 GUPnPServiceProxyAction *
 gupnp_service_proxy_action_new (const char *action,
                                 ...)
@@ -308,6 +356,45 @@ gupnp_service_proxy_action_new (const char *action,
  * names (as strings)
  * @in_values: (element-type GValue) (transfer none): #GList of values (as
  * #GValue) that line up with @in_names
+ *
+ * Prepares action @action with parameters @in_names and @in_values to be
+ * sent off to a remote service later with gupnp_service_proxy_call_action() or
+ * gupnp_service_proxy_call_action_async(). This is mainly useful for language
+ * bindings.
+ *
+ * After the action call has finished, the results of the call may be
+ * retrived from the #GUPnPServiceProxyAction by using
+ * gupnp_service_proxy_action_get_result(),
+ * gupnp_service_proxy_action_get_result_list() or
+ * gupnp_service_proxy_action_get_result_hash()
+ * <informalexample>
+ * <programlisting>
+ * GList *in_args = NULL;
+ * in_args = g_list_append (in_args, "InstanceID");
+ * in_args = g_list_append (in_args, "Unit");
+ * in_args = g_list_append (in_args, "Target");
+ *
+ * GValue instance = G_VALUE_INIT;
+ * g_value_set_int (&instance, 0);
+ * GValue unit = G_VALUE_INIT;
+ * g_value_set_static_string (&unit, "ABS_TIME");
+ * GValue target = G_VALUE_INIT;
+ * g_value_set_static_string (&target, "00:00:00.000");
+ * GList *in_values = NULL;
+ * in_values = g_list_append (in_values, &instance);
+ * in_values = g_list_append (in_values, &unit);
+ * in_values = g_list_append (in_values, &target);
+ *
+ * GUPnPServiceProxyAction *action =
+ *         gunp_service_proxy_action_new_from_list ("Seek", in_args, in_values);
+ *
+ * GError *error = NULL;
+ * gupnp_service_proxy_call_action_async (proxy, action, NULL, on_action_finished, NULL);
+ * gupnp_service_proxy_action_unref (action);
+ * </programlisting>
+ * </informalexample>
+ *
+ * Returns: A newly created #GUPnPServiceProxyAction
  */
 GUPnPServiceProxyAction *
 gupnp_service_proxy_action_new_from_list (const char *action_name,