docs: update utils documentation

2 files changed, 478 insertions, 402 deletions

diff --git a/src/libqmi-glib/qmi-utils.c b/src/libqmi-glib/qmi-utils.c
index 813c56d..29e5f22 100644
--- a/src/libqmi-glib/qmi-utils.c
+++ b/src/libqmi-glib/qmi-utils.c
@@ -143,20 +143,6 @@ print_read_bytes_trace (const gchar *type,
 #define print_read_bytes_trace(...)
 #endif
 
-/**
- * qmi_utils_read_guint8_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @out: return location for the read variable.
- *
- * Reads an unsigned byte from the buffer.
- *
- * The user needs to make sure that at least 1 byte is available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 1 byte
- * read.
- */
 void
 qmi_utils_read_guint8_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -175,20 +161,6 @@ qmi_utils_read_guint8_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 1;
 }
 
-/**
- * qmi_utils_read_gint8_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @out: return location for the read variable.
- *
- * Reads a signed byte from the buffer.
- *
- * The user needs to make sure that at least 1 byte is available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 1 byte
- * read.
- */
 void
 qmi_utils_read_gint8_from_buffer (const guint8 **buffer,
                                   guint16       *buffer_size,
@@ -207,23 +179,6 @@ qmi_utils_read_gint8_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 1;
 }
 
-/**
- * qmi_utils_read_guint16_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads an unsigned 16-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specificed by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 2 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 2 bytes
- * read.
- */
 void
 qmi_utils_read_guint16_from_buffer (const guint8 **buffer,
                                     guint16       *buffer_size,
@@ -247,23 +202,6 @@ qmi_utils_read_guint16_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 2;
 }
 
-/**
- * qmi_utils_read_gint16_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads a signed 16-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specified by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 2 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 2 bytes
- * read.
- */
 void
 qmi_utils_read_gint16_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -287,23 +225,6 @@ qmi_utils_read_gint16_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 2;
 }
 
-/**
- * qmi_utils_read_guint32_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads an unsigned 32-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specified by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 4 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 4 bytes
- * read.
- */
 void
 qmi_utils_read_guint32_from_buffer (const guint8 **buffer,
                                     guint16       *buffer_size,
@@ -327,23 +248,6 @@ qmi_utils_read_guint32_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 4;
 }
 
-/**
- * qmi_utils_read_gint32_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads a signed 32-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specified by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 4 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 4 bytes
- * read.
- */
 void
 qmi_utils_read_gint32_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -367,23 +271,6 @@ qmi_utils_read_gint32_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 4;
 }
 
-/**
- * qmi_utils_read_guint64_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads an unsigned 64-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specified by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 8 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 8 bytes
- * read.
- */
 void
 qmi_utils_read_guint64_from_buffer (const guint8 **buffer,
                                     guint16       *buffer_size,
@@ -407,23 +294,6 @@ qmi_utils_read_guint64_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 8;
 }
 
-/**
- * qmi_utils_read_gint64_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads a signed 64-bit integer from the buffer. The number in the buffer is
- * expected to be given in the byte order specified by @endian, and this method
- * takes care of converting the read value to the proper host endianness.
- *
- * The user needs to make sure that at least 8 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 8 bytes
- * read.
- */
 void
 qmi_utils_read_gint64_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -447,25 +317,6 @@ qmi_utils_read_gint64_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 8;
 }
 
-/**
- * qmi_utils_read_sized_guint_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @n_bytes: number of bytes to read.
- * @endian: endianness of firmware value; swapped to host byte order if necessary
- * @out: return location for the read variable.
- *
- * Reads a @n_bytes-sized unsigned integer from the buffer. The number in the
- * buffer is expected to be given in the byte order specified by @endian, and
- * this method takes care of converting the read value to the proper host
- * endianness.
- *
- * The user needs to make sure that at least @n_bytes bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the @n_bytes
- * bytes read.
- */
 void
 qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer,
                                         guint16       *buffer_size,
@@ -500,20 +351,6 @@ qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - n_bytes;
 }
 
-/**
- * qmi_utils_read_gfloat_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @out: return location for the read variable.
- *
- * Reads a 32-bit floating-point number from the buffer.
- *
- * The user needs to make sure that at least 4 bytes are available
- * in the buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the 4 bytes
- * read.
- */
 void
 qmi_utils_read_gfloat_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -533,19 +370,6 @@ qmi_utils_read_gfloat_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - 4;
 }
 
-/**
- * qmi_utils_write_guint8_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @in: location of the variable to be written.
- *
- * Writes an unsigned byte into the buffer.
- *
- * The user needs to make sure that the buffer is at least 1 byte long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 1 byte
- * write.
- */
 void
 qmi_utils_write_guint8_to_buffer (guint8  **buffer,
                                   guint16  *buffer_size,
@@ -562,19 +386,6 @@ qmi_utils_write_guint8_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 1;
 }
 
-/**
- * qmi_utils_write_gint8_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @in: location of the variable to be written.
- *
- * Writes a signed byte into the buffer.
- *
- * The user needs to make sure that the buffer is at least 1 byte long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 1 byte
- * write.
- */
 void
 qmi_utils_write_gint8_to_buffer (guint8  **buffer,
                                  guint16  *buffer_size,
@@ -591,22 +402,6 @@ qmi_utils_write_gint8_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 1;
 }
 
-/**
- * qmi_utils_write_guint16_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes an unsigned 16-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 2 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 2 bytes
- * write.
- */
 void
 qmi_utils_write_guint16_to_buffer (guint8  **buffer,
                                    guint16  *buffer_size,
@@ -630,22 +425,6 @@ qmi_utils_write_guint16_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 2;
 }
 
-/**
- * qmi_utils_write_gint16_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes a signed 16-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 2 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 2 bytes
- * write.
- */
 void
 qmi_utils_write_gint16_to_buffer (guint8  **buffer,
                                   guint16  *buffer_size,
@@ -669,22 +448,6 @@ qmi_utils_write_gint16_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 2;
 }
 
-/**
- * qmi_utils_write_guint32_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes an unsigned 32-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 4 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 4 bytes
- * write.
- */
 void
 qmi_utils_write_guint32_to_buffer (guint8  **buffer,
                                    guint16  *buffer_size,
@@ -708,22 +471,6 @@ qmi_utils_write_guint32_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 4;
 }
 
-/**
- * qmi_utils_write_gint32_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes a signed 32-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 4 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 4 bytes
- * write.
- */
 void
 qmi_utils_write_gint32_to_buffer (guint8  **buffer,
                                   guint16  *buffer_size,
@@ -747,22 +494,6 @@ qmi_utils_write_gint32_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 4;
 }
 
-/**
- * qmi_utils_write_guint64_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes an unsigned 64-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 8 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 8 bytes
- * write.
- */
 void
 qmi_utils_write_guint64_to_buffer (guint8  **buffer,
                                    guint16  *buffer_size,
@@ -786,22 +517,6 @@ qmi_utils_write_guint64_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 8;
 }
 
-/**
- * qmi_utils_write_gint64_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes a signed 64-bit integer into the buffer. The number to be written
- * is expected to be given in host endianness, and this method takes care of
- * converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least 8 bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the 8 bytes
- * write.
- */
 void
 qmi_utils_write_gint64_to_buffer (guint8  **buffer,
                                   guint16  *buffer_size,
@@ -825,23 +540,6 @@ qmi_utils_write_gint64_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - 8;
 }
 
-/**
- * qmi_utils_write_sized_guint_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @n_bytes: number of bytes to write.
- * @endian: endianness of firmware value; swapped from host byte order if necessary
- * @in: location of the variable to be written.
- *
- * Writes a @n_bytes-sized unsigned integer into the buffer. The number to be
- * written is expected to be given in host endianness, and this method takes
- * care of converting the value written to the byte order specified by @endian.
- *
- * The user needs to make sure that the buffer is at least @n_bytes bytes long.
- *
- * Also note that both @buffer and @buffer_size get updated after the @n_bytes
- * bytes write.
- */
 void
 qmi_utils_write_sized_guint_to_buffer (guint8  **buffer,
                                        guint16  *buffer_size,
@@ -878,21 +576,6 @@ qmi_utils_write_sized_guint_to_buffer (guint8  **buffer,
     *buffer_size = (*buffer_size) - n_bytes;
 }
 
-/**
- * qmi_utils_read_string_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @length_prefix_size: size of the length prefix integer in bits.
- * @max_size: maximum number of bytes to read, or 0 to read all available bytes.
- * @out: return location for the read string. The returned value should be freed with g_free().
- *
- * Reads a string from the buffer.
- *
- * If @length_prefix_size is greater than 0, only the amount of bytes given
- * there will be read. Otherwise, up to @buffer_size bytes will be read.
- *
- * Also note that both @buffer and @buffer_size get updated after the write.
- */
 void
 qmi_utils_read_string_from_buffer (const guint8 **buffer,
                                    guint16       *buffer_size,
@@ -949,18 +632,6 @@ qmi_utils_read_string_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - string_length;
 }
 
-/**
- * qmi_utils_read_fixed_size_string_from_buffer:
- * @buffer: a buffer with raw binary data.
- * @buffer_size: size of @buffer.
- * @fixed_size: number of bytes to read.
- * @out: buffer preallocated by the client, with at least @fixed_size bytes.
- *
- * Reads a @fixed_size-sized string from the buffer into the @out buffer.
- *
- * Also note that both @buffer and @buffer_size get updated after the
- * @fixed_size bytes read.
- */
 void
 qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer,
                                               guint16       *buffer_size,
@@ -978,23 +649,6 @@ qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer,
     *buffer_size = (*buffer_size) - fixed_size;
 }
 
-/**
- * qmi_utils_write_string_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @length_prefix_size: size of the length prefix integer in bits.
- * @in: string to write.
- *
- * Writes a string to the buffer.
- *
- * If @length_prefix_size is greater than 0, a length prefix integer will be
- * included in the write operation.
- *
- * The user needs to make sure that the buffer has enough space for both the
- * whole string and the length prefix.
- *
- * Also note that both @buffer and @buffer_size get updated after the write.
- */
 void
 qmi_utils_write_string_to_buffer (guint8      **buffer,
                                   guint16      *buffer_size,
@@ -1047,21 +701,6 @@ qmi_utils_write_string_to_buffer (guint8      **buffer,
     *buffer_size = (*buffer_size) - len;
 }
 
-/**
- * qmi_utils_write_fixed_size_string_to_buffer:
- * @buffer: a buffer.
- * @buffer_size: size of @buffer.
- * @fixed_size: number of bytes to write.
- * @in: string to write.
- *
- * Writes a @fixed_size-sized string to the buffer, without any length prefix.
- *
- * The user needs to make sure that the buffer is at least @fixed_size bytes
- * long.
- *
- * Also note that both @buffer and @buffer_size get updated after the
- * @fixed_size bytes write.
- */
 void
 qmi_utils_write_fixed_size_string_to_buffer (guint8      **buffer,
                                              guint16      *buffer_size,
@@ -1118,25 +757,12 @@ __qmi_utils_get_driver (const gchar *cdc_wdm_path)
 
 static volatile gint __traces_enabled = FALSE;
 
-/**
- * qmi_utils_get_traces_enabled:
- *
- * Checks whether QMI message traces are currently enabled.
- *
- * Returns: %TRUE if traces are enabled, %FALSE otherwise.
- */
 gboolean
 qmi_utils_get_traces_enabled (void)
 {
     return (gboolean) g_atomic_int_get (&__traces_enabled);
 }
 
-/**
- * qmi_utils_set_traces_enabled:
- * @enabled: %TRUE to enable traces, %FALSE to disable them.
- *
- * Sets whether QMI message traces are enabled or disabled.
- */
 void
 qmi_utils_set_traces_enabled (gboolean enabled)
 {
diff --git a/src/libqmi-glib/qmi-utils.h b/src/libqmi-glib/qmi-utils.h
index c03bd89..4fd5199 100644
--- a/src/libqmi-glib/qmi-utils.h
+++ b/src/libqmi-glib/qmi-utils.h
@@ -39,6 +39,8 @@ G_BEGIN_DECLS
  * @QMI_ENDIAN_BIG: Big endian.
  *
  * Type of endianness
+ *
+ * Since: 1.0
  */
 typedef enum {
     QMI_ENDIAN_LITTLE = 0,
@@ -47,111 +49,470 @@ typedef enum {
 
 /* Reading/Writing integer variables */
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_guint8_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @out: return location for the read variable.
+ *
+ * Reads an unsigned byte from the buffer.
+ *
+ * The user needs to make sure that at least 1 byte is available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 1 byte
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_guint8() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_guint8)
 void qmi_utils_read_guint8_from_buffer  (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          guint8        *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_gint8_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @out: return location for the read variable.
+ *
+ * Reads a signed byte from the buffer.
+ *
+ * The user needs to make sure that at least 1 byte is available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 1 byte
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_gint8() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_gint8)
 void qmi_utils_read_gint8_from_buffer   (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          gint8         *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_guint16_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads an unsigned 16-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specificed by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 2 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 2 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_guint16() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_guint16)
 void qmi_utils_read_guint16_from_buffer (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          guint16       *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_gint16_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads a signed 16-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specified by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 2 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 2 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_gint16() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_gint16)
 void qmi_utils_read_gint16_from_buffer  (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          gint16        *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_guint32_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads an unsigned 32-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specified by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 4 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 4 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_guint32() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_guint32)
 void qmi_utils_read_guint32_from_buffer (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          guint32       *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_gint32_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads a signed 32-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specified by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 4 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 4 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_gint32() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_gint32)
 void qmi_utils_read_gint32_from_buffer  (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          gint32        *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_guint64_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads an unsigned 64-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specified by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 8 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 8 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_guint64() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_guint64)
 void qmi_utils_read_guint64_from_buffer (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          guint64       *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_gint64_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads a signed 64-bit integer from the buffer. The number in the buffer is
+ * expected to be given in the byte order specified by @endian, and this method
+ * takes care of converting the read value to the proper host endianness.
+ *
+ * The user needs to make sure that at least 8 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 8 bytes
+ * read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_gint64() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_gint64)
 void qmi_utils_read_gint64_from_buffer  (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          QmiEndian      endian,
                                          gint64        *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_sized_guint_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @n_bytes: number of bytes to read.
+ * @endian: endianness of firmware value; swapped to host byte order if necessary
+ * @out: return location for the read variable.
+ *
+ * Reads a @n_bytes-sized unsigned integer from the buffer. The number in the
+ * buffer is expected to be given in the byte order specified by @endian, and
+ * this method takes care of converting the read value to the proper host
+ * endianness.
+ *
+ * The user needs to make sure that at least @n_bytes bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the @n_bytes
+ * bytes read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_sized_guint() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_sized_guint)
 void qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer,
                                              guint16       *buffer_size,
                                              guint          n_bytes,
                                              QmiEndian      endian,
                                              guint64       *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_gfloat_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @out: return location for the read variable.
+ *
+ * Reads a 32-bit floating-point number from the buffer.
+ *
+ * The user needs to make sure that at least 4 bytes are available
+ * in the buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 4 bytes
+ * read.
+ *
+ * Since: 1.10
+ * Deprecated: 1.12: Use qmi_message_tlv_read_gfloat() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_gfloat)
 void qmi_utils_read_gfloat_from_buffer  (const guint8 **buffer,
                                          guint16       *buffer_size,
                                          gfloat        *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_guint8_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @in: location of the variable to be written.
+ *
+ * Writes an unsigned byte into the buffer.
+ *
+ * The user needs to make sure that the buffer is at least 1 byte long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 1 byte
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_guint8() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_guint8)
 void qmi_utils_write_guint8_to_buffer (guint8  **buffer,
                                        guint16  *buffer_size,
                                        guint8   *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_gint8_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @in: location of the variable to be written.
+ *
+ * Writes a signed byte into the buffer.
+ *
+ * The user needs to make sure that the buffer is at least 1 byte long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 1 byte
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_gint8() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_gint8)
 void qmi_utils_write_gint8_to_buffer  (guint8  **buffer,
                                        guint16  *buffer_size,
                                        gint8    *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_guint16_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes an unsigned 16-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 2 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 2 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_guint16() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_guint16)
 void qmi_utils_write_guint16_to_buffer (guint8  **buffer,
                                         guint16  *buffer_size,
                                         QmiEndian endian,
                                         guint16  *in);
 
-G_DEPRECATED
-void qmi_utils_write_gint16_to_buffer  (guint8  **buffer,
-                                        guint16  *buffer_size,
-                                        QmiEndian endian,
-                                        gint16   *in);
+/**
+ * qmi_utils_write_gint16_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes a signed 16-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 2 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 2 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_gint16() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_gint16)
+void qmi_utils_write_gint16_to_buffer (guint8  **buffer,
+                                       guint16  *buffer_size,
+                                       QmiEndian endian,
+                                       gint16   *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_guint32_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes an unsigned 32-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 4 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 4 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_guint32() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_guint32)
 void qmi_utils_write_guint32_to_buffer (guint8  **buffer,
                                         guint16  *buffer_size,
                                         QmiEndian endian,
                                         guint32  *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_gint32_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes a signed 32-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 4 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 4 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_gint32() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_gint32)
 void qmi_utils_write_gint32_to_buffer  (guint8  **buffer,
                                         guint16  *buffer_size,
                                         QmiEndian endian,
                                         gint32   *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_guint64_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes an unsigned 64-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 8 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 8 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_guint64() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_guint64)
 void qmi_utils_write_guint64_to_buffer (guint8  **buffer,
                                         guint16  *buffer_size,
                                         QmiEndian endian,
                                         guint64  *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_gint64_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes a signed 64-bit integer into the buffer. The number to be written
+ * is expected to be given in host endianness, and this method takes care of
+ * converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least 8 bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the 8 bytes
+ * write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_gint64() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_gint64)
 void qmi_utils_write_gint64_to_buffer  (guint8  **buffer,
                                         guint16  *buffer_size,
                                         QmiEndian endian,
                                         gint64   *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_sized_guint_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @n_bytes: number of bytes to write.
+ * @endian: endianness of firmware value; swapped from host byte order if necessary
+ * @in: location of the variable to be written.
+ *
+ * Writes a @n_bytes-sized unsigned integer into the buffer. The number to be
+ * written is expected to be given in host endianness, and this method takes
+ * care of converting the value written to the byte order specified by @endian.
+ *
+ * The user needs to make sure that the buffer is at least @n_bytes bytes long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the @n_bytes
+ * bytes write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_sized_guint() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_sized_guint)
 void qmi_utils_write_sized_guint_to_buffer (guint8  **buffer,
                                             guint16  *buffer_size,
                                             guint     n_bytes,
@@ -160,34 +521,123 @@ void qmi_utils_write_sized_guint_to_buffer (guint8  **buffer,
 
 /* Reading/Writing string variables */
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_string_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @length_prefix_size: size of the length prefix integer in bits.
+ * @max_size: maximum number of bytes to read, or 0 to read all available bytes.
+ * @out: return location for the read string. The returned value should be freed with g_free().
+ *
+ * Reads a string from the buffer.
+ *
+ * If @length_prefix_size is greater than 0, only the amount of bytes given
+ * there will be read. Otherwise, up to @buffer_size bytes will be read.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_string() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_string)
 void qmi_utils_read_string_from_buffer (const guint8 **buffer,
                                         guint16       *buffer_size,
                                         guint8         length_prefix_size,
                                         guint16        max_size,
                                         gchar        **out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_string_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @length_prefix_size: size of the length prefix integer in bits.
+ * @in: string to write.
+ *
+ * Writes a string to the buffer.
+ *
+ * If @length_prefix_size is greater than 0, a length prefix integer will be
+ * included in the write operation.
+ *
+ * The user needs to make sure that the buffer has enough space for both the
+ * whole string and the length prefix.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_string() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_string)
 void qmi_utils_write_string_to_buffer  (guint8      **buffer,
                                         guint16      *buffer_size,
                                         guint8        length_prefix_size,
                                         const gchar  *in);
 
-G_DEPRECATED
+/**
+ * qmi_utils_read_fixed_size_string_from_buffer:
+ * @buffer: a buffer with raw binary data.
+ * @buffer_size: size of @buffer.
+ * @fixed_size: number of bytes to read.
+ * @out: buffer preallocated by the client, with at least @fixed_size bytes.
+ *
+ * Reads a @fixed_size-sized string from the buffer into the @out buffer.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the
+ * @fixed_size bytes read.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_read_fixed_size_string() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_read_fixed_size_string)
 void qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer,
                                                    guint16       *buffer_size,
                                                    guint16        fixed_size,
                                                    gchar         *out);
 
-G_DEPRECATED
+/**
+ * qmi_utils_write_fixed_size_string_to_buffer:
+ * @buffer: a buffer.
+ * @buffer_size: size of @buffer.
+ * @fixed_size: number of bytes to write.
+ * @in: string to write.
+ *
+ * Writes a @fixed_size-sized string to the buffer, without any length prefix.
+ *
+ * The user needs to make sure that the buffer is at least @fixed_size bytes
+ * long.
+ *
+ * Also note that both @buffer and @buffer_size get updated after the
+ * @fixed_size bytes write.
+ *
+ * Since: 1.0
+ * Deprecated: 1.12: Use qmi_message_tlv_write_string() instead.
+ */
+G_DEPRECATED_FOR (qmi_message_tlv_write_string)
 void qmi_utils_write_fixed_size_string_to_buffer  (guint8      **buffer,
                                                    guint16      *buffer_size,
                                                    guint16       fixed_size,
                                                    const gchar  *in);
 
 /* Enabling/Disabling traces */
+/**
+ * qmi_utils_get_traces_enabled:
+ *
+ * Checks whether QMI message traces are currently enabled.
+ *
+ * Returns: %TRUE if traces are enabled, %FALSE otherwise.
+ *
+ * Since: 1.0
+ */
 gboolean qmi_utils_get_traces_enabled (void);
-void     qmi_utils_set_traces_enabled (gboolean enabled);
+
+/**
+ * qmi_utils_set_traces_enabled:
+ * @enabled: %TRUE to enable traces, %FALSE to disable them.
+ *
+ * Sets whether QMI message traces are enabled or disabled.
+ *
+ * Since: 1.0
+ */
+void qmi_utils_set_traces_enabled (gboolean enabled);
 
 /* Other private methods */