docs: update QmiClient documentation

2 files changed, 193 insertions, 93 deletions

diff --git a/src/libqmi-glib/qmi-client.c b/src/libqmi-glib/qmi-client.c
index 8345dde..5ea0aba 100644
--- a/src/libqmi-glib/qmi-client.c
+++ b/src/libqmi-glib/qmi-client.c
@@ -28,20 +28,7 @@
 #include "qmi-client.h"
 #include "qmi-ctl.h"
 
-/**
- * SECTION:qmi-client
- * @title: QmiClient
- * @short_description: Generic QMI client handling routines
- *
- * #QmiClient is a generic type representing a QMI client for any kind of
- * #QmiService.
- *
- * These objects are created by a #QmiDevice with qmi_device_allocate_client(),
- * and before completely disposing them qmi_device_release_client() needs to be
- * called in order to release the unique client ID reserved.
- */
-
-G_DEFINE_ABSTRACT_TYPE (QmiClient, qmi_client, G_TYPE_OBJECT);
+G_DEFINE_ABSTRACT_TYPE (QmiClient, qmi_client, G_TYPE_OBJECT)
 
 enum {
     PROP_0,
@@ -67,14 +54,6 @@ struct _QmiClientPrivate {
 
 /*****************************************************************************/
 
-/**
- * qmi_client_get_device:
- * @self: a #QmiClient
- *
- * Get the #QmiDevice associated with this #QmiClient.
- *
- * Returns: a #GObject that must be freed with g_object_unref().
- */
 GObject *
 qmi_client_get_device (QmiClient *self)
 {
@@ -89,15 +68,6 @@ qmi_client_get_device (QmiClient *self)
     return device;
 }
 
-/**
- * qmi_client_peek_device:
- * @self: a #QmiClient.
- *
- * Get the #QmiDevice associated with this #QmiClient, without increasing the reference count
- * on the returned object.
- *
- * Returns: a #GObject. Do not free the returned object, it is owned by @self.
- */
 GObject *
 qmi_client_peek_device (QmiClient *self)
 {
@@ -106,14 +76,6 @@ qmi_client_peek_device (QmiClient *self)
     return G_OBJECT (self->priv->device);
 }
 
-/**
- * qmi_client_get_service:
- * @self: A #QmiClient
- *
- * Get the service being used by this #QmiClient.
- *
- * Returns: a #QmiService.
- */
 QmiService
 qmi_client_get_service (QmiClient *self)
 {
@@ -122,14 +84,6 @@ qmi_client_get_service (QmiClient *self)
     return self->priv->service;
 }
 
-/**
- * qmi_client_get_cid:
- * @self: A #QmiClient
- *
- * Get the client ID of this #QmiClient.
- *
- * Returns: the client ID.
- */
 guint8
 qmi_client_get_cid (QmiClient *self)
 {
@@ -138,16 +92,6 @@ qmi_client_get_cid (QmiClient *self)
     return self->priv->cid;
 }
 
-/**
- * qmi_client_get_version:
- * @self: A #QmiClient
- * @major: placeholder for the output major version.
- * @minor: placeholder for the output minor version.
- *
- * Get the version of the service handled by this #QmiClient.
- *
- * Returns: %TRUE if the version was properly reported, %FALSE otherwise.
- */
 gboolean
 qmi_client_get_version (QmiClient *self,
                         guint *major,
@@ -165,17 +109,6 @@ qmi_client_get_version (QmiClient *self,
     return TRUE;
 }
 
-/**
- * qmi_client_check_version:
- * @self: A #QmiClient
- * @major: a major version.
- * @minor: a minor version.
- *
- * Checks if the version of the service handled by this #QmiClient is greater
- * or equal than the given version.
- *
- * Returns: %TRUE if the version of the service is greater or equal than the one given, %FALSE otherwise.
- */
 gboolean
 qmi_client_check_version (QmiClient *self,
                           guint major,
@@ -196,15 +129,6 @@ qmi_client_check_version (QmiClient *self,
     return FALSE;
 }
 
-/**
- * qmi_client_get_next_transaction_id:
- * @self: A #QmiClient
- *
- * Acquire the next transaction ID of this #QmiClient.
- * The internal transaction ID gets incremented.
- *
- * Returns: the next transaction ID.
- */
 guint16
 qmi_client_get_next_transaction_id (QmiClient *self)
 {
@@ -325,6 +249,11 @@ qmi_client_class_init (QmiClientClass *klass)
     object_class->get_property = get_property;
     object_class->set_property = set_property;
 
+    /**
+     * QmiClient:client-device:
+     *
+     * Since: 1.0
+     */
     properties[PROP_DEVICE] =
         g_param_spec_object (QMI_CLIENT_DEVICE,
                              "Device",
@@ -333,6 +262,11 @@ qmi_client_class_init (QmiClientClass *klass)
                              G_PARAM_READWRITE);
     g_object_class_install_property (object_class, PROP_DEVICE, properties[PROP_DEVICE]);
 
+    /**
+     * QmiClient:client-service:
+     *
+     * Since: 1.0
+     */
     properties[PROP_SERVICE] =
         g_param_spec_enum (QMI_CLIENT_SERVICE,
                            "Service",
@@ -342,6 +276,11 @@ qmi_client_class_init (QmiClientClass *klass)
                            G_PARAM_READWRITE);
     g_object_class_install_property (object_class, PROP_SERVICE, properties[PROP_SERVICE]);
 
+    /**
+     * QmiClient:client-cid:
+     *
+     * Since: 1.0
+     */
     properties[PROP_CID] =
         g_param_spec_uint (QMI_CLIENT_CID,
                            "Client ID",
@@ -352,6 +291,11 @@ qmi_client_class_init (QmiClientClass *klass)
                            G_PARAM_READWRITE);
     g_object_class_install_property (object_class, PROP_CID, properties[PROP_CID]);
 
+    /**
+     * QmiClient:client-version-major:
+     *
+     * Since: 1.0
+     */
     properties[PROP_VERSION_MAJOR] =
         g_param_spec_uint (QMI_CLIENT_VERSION_MAJOR,
                            "Version major",
@@ -362,6 +306,11 @@ qmi_client_class_init (QmiClientClass *klass)
                            G_PARAM_READWRITE);
     g_object_class_install_property (object_class, PROP_VERSION_MAJOR, properties[PROP_VERSION_MAJOR]);
 
+    /**
+     * QmiClient:client-version-minor:
+     *
+     * Since: 1.0
+     */
     properties[PROP_VERSION_MINOR] =
         g_param_spec_uint (QMI_CLIENT_VERSION_MINOR,
                            "Version minor",
diff --git a/src/libqmi-glib/qmi-client.h b/src/libqmi-glib/qmi-client.h
index 3d4990f..6f1fb4b 100644
--- a/src/libqmi-glib/qmi-client.h
+++ b/src/libqmi-glib/qmi-client.h
@@ -34,7 +34,35 @@
 
 G_BEGIN_DECLS
 
-#define QMI_CID_NONE      0x00
+/**
+ * SECTION:qmi-client
+ * @title: QmiClient
+ * @short_description: Generic QMI client handling routines
+ *
+ * #QmiClient is a generic type representing a QMI client for any kind of
+ * #QmiService.
+ *
+ * These objects are created by a #QmiDevice with qmi_device_allocate_client(),
+ * and before completely disposing them qmi_device_release_client() needs to be
+ * called in order to release the unique client ID reserved.
+ */
+
+/**
+ * QMI_CID_NONE:
+ *
+ * A symbol specifying a special CID value that references no CID.
+ *
+ * Since: 1.0
+ */
+#define QMI_CID_NONE 0x00
+
+/**
+ * QMI_CID_BROADCAST:
+ *
+ * A symbol specifying the broadcast CID.
+ *
+ * Since: 1.0
+ */
 #define QMI_CID_BROADCAST 0xFF
 
 #define QMI_TYPE_CLIENT            (qmi_client_get_type ())
@@ -48,10 +76,49 @@ typedef struct _QmiClient QmiClient;
 typedef struct _QmiClientClass QmiClientClass;
 typedef struct _QmiClientPrivate QmiClientPrivate;
 
-#define QMI_CLIENT_DEVICE        "client-device"
-#define QMI_CLIENT_SERVICE       "client-service"
-#define QMI_CLIENT_CID           "client-cid"
+/**
+ * QMI_CLIENT_DEVICE:
+ *
+ * Symbol defining the #QmiClient:client-device property.
+ *
+ * Since: 1.0
+ */
+#define QMI_CLIENT_DEVICE "client-device"
+
+/**
+ * QMI_CLIENT_SERVICE:
+ *
+ * Symbol defining the #QmiClient:client-service property.
+ *
+ * Since: 1.0
+ */
+#define QMI_CLIENT_SERVICE "client-service"
+
+/**
+ * QMI_CLIENT_CID:
+ *
+ * Symbol defining the #QmiClient:client-cid property.
+ *
+ * Since: 1.0
+ */
+#define QMI_CLIENT_CID "client-cid"
+
+/**
+ * QMI_CLIENT_VERSION_MAJOR:
+ *
+ * Symbol defining the #QmiClient:client-version-major property.
+ *
+ * Since: 1.0
+ */
 #define QMI_CLIENT_VERSION_MAJOR "client-version-major"
+
+/**
+ * QMI_CLIENT_VERSION_MINOR:
+ *
+ * Symbol defining the #QmiClient:client-version-minor property.
+ *
+ * Since: 1.0
+ */
 #define QMI_CLIENT_VERSION_MINOR "client-version-minor"
 
 /**
@@ -59,6 +126,8 @@ typedef struct _QmiClientPrivate QmiClientPrivate;
  *
  * The #QmiClient structure contains private data and should only be accessed
  * using the provided API.
+ *
+ * Since: 1.0
  */
 struct _QmiClient {
     /*< private >*/
@@ -77,24 +146,106 @@ struct _QmiClientClass {
 
 GType qmi_client_get_type (void);
 
-GObject    *qmi_client_get_device  (QmiClient *self);
-GObject    *qmi_client_peek_device (QmiClient *self);
-QmiService  qmi_client_get_service (QmiClient *self);
-guint8      qmi_client_get_cid     (QmiClient *self);
-gboolean    qmi_client_get_version (QmiClient *self,
-                                    guint *major,
-                                    guint *minor);
-gboolean    qmi_client_check_version (QmiClient *self,
-                                      guint major,
-                                      guint minor);
+/**
+ * qmi_client_get_device:
+ * @self: a #QmiClient
+ *
+ * Get the #QmiDevice associated with this #QmiClient.
+ *
+ * Returns: a #GObject that must be freed with g_object_unref().
+ *
+ * Since: 1.0
+ */
+GObject *qmi_client_get_device (QmiClient *self);
+
+/**
+ * qmi_client_peek_device:
+ * @self: a #QmiClient.
+ *
+ * Get the #QmiDevice associated with this #QmiClient, without increasing the reference count
+ * on the returned object.
+ *
+ * Returns: a #GObject. Do not free the returned object, it is owned by @self.
+ *
+ * Since: 1.0
+ */
+GObject *qmi_client_peek_device (QmiClient *self);
 
-guint16     qmi_client_get_next_transaction_id (QmiClient *self);
+/**
+ * qmi_client_get_service:
+ * @self: A #QmiClient
+ *
+ * Get the service being used by this #QmiClient.
+ *
+ * Returns: a #QmiService.
+ *
+ * Since: 1.0
+ */
+QmiService qmi_client_get_service (QmiClient *self);
+
+/**
+ * qmi_client_get_cid:
+ * @self: A #QmiClient
+ *
+ * Get the client ID of this #QmiClient.
+ *
+ * Returns: the client ID.
+ *
+ * Since: 1.0
+ */
+guint8 qmi_client_get_cid (QmiClient *self);
+
+/**
+ * qmi_client_get_version:
+ * @self: A #QmiClient
+ * @major: placeholder for the output major version.
+ * @minor: placeholder for the output minor version.
+ *
+ * Get the version of the service handled by this #QmiClient.
+ *
+ * Returns: %TRUE if the version was properly reported, %FALSE otherwise.
+ *
+ * Since: 1.0
+ */
+gboolean qmi_client_get_version (QmiClient *self,
+                                 guint     *major,
+                                 guint     *minor);
+
+/**
+ * qmi_client_check_version:
+ * @self: A #QmiClient
+ * @major: a major version.
+ * @minor: a minor version.
+ *
+ * Checks if the version of the service handled by this #QmiClient is greater
+ * or equal than the given version.
+ *
+ * Returns: %TRUE if the version of the service is greater or equal than the one given, %FALSE otherwise.
+ *
+ * Since: 1.0
+ */
+gboolean qmi_client_check_version (QmiClient *self,
+                                   guint      major,
+                                   guint      minor);
+
+/**
+ * qmi_client_get_next_transaction_id:
+ * @self: A #QmiClient
+ *
+ * Acquire the next transaction ID of this #QmiClient.
+ * The internal transaction ID gets incremented.
+ *
+ * Returns: the next transaction ID.
+ *
+ * Since: 1.0
+ */
+guint16 qmi_client_get_next_transaction_id (QmiClient *self);
 
 /* not part of the public API */
 
 #if defined (LIBQMI_GLIB_COMPILATION)
 G_GNUC_INTERNAL
-void __qmi_client_process_indication (QmiClient *self,
+void __qmi_client_process_indication (QmiClient  *self,
                                       QmiMessage *message);
 #endif