Add docs and return_if_fail stuff for GDBusMessage

3 files changed, 392 insertions, 9 deletions

diff --git a/gdbus/gdbusenums.h b/gdbus/gdbusenums.h
index fa86ae2..a13ead7 100644
--- a/gdbus/gdbusenums.h
+++ b/gdbus/gdbusenums.h
@@ -339,7 +339,7 @@ typedef enum {
  * @G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION: The name the message is intended for.
  * @G_DBUS_MESSAGE_HEADER_FIELD_SENDER: Unique name of the sender of the message (filled in by the bus).
  * @G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE: The signature of the message body.
- * @G_DBUS_MESSAGE_HEADER_FIELD_UNIX_FDS: The number of UNIX file descriptors that accompany the message.
+ * @G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS: The number of UNIX file descriptors that accompany the message.
  *
  * Header fields used in #GDBusMessage.
  */
diff --git a/gdbus/gdbusmessage.c b/gdbus/gdbusmessage.c
index dc2d9b7..2a6db5b 100644
--- a/gdbus/gdbusmessage.c
+++ b/gdbus/gdbusmessage.c
@@ -34,7 +34,8 @@
  * @short_description: D-Bus Message
  * @include: gdbus/gdbus.h
  *
- * TODO
+ * A type for representing D-Bus messages that can be sent or received
+ * on a #GDBusConnection.
  */
 
 struct _GDBusMessagePrivate
@@ -95,12 +96,30 @@ g_dbus_message_init (GDBusMessage *message)
                                                   (GDestroyNotify) g_variant_unref);
 }
 
+/**
+ * g_dbus_message_new:
+ *
+ * Creates a new empty #GDBusMessage.
+ *
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new (void)
 {
   return g_object_new (G_TYPE_DBUS_MESSAGE, NULL);
 }
 
+/**
+ * g_dbus_message_new_method_call:
+ * @name: A valid D-Bus name or %NULL.
+ * @path: A valid object path.
+ * @interface: A valid D-Bus interface name or %NULL.
+ * @method: A valid method name.
+ *
+ * Creates a new #GDBusMessage for a method call.
+ *
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new_method_call (const gchar *name,
                                 const gchar *path,
@@ -111,7 +130,7 @@ g_dbus_message_new_method_call (const gchar *name,
 
   g_return_val_if_fail (name == NULL || g_dbus_is_name (name), NULL);
   g_return_val_if_fail (g_variant_is_object_path (path), NULL);
-  g_return_val_if_fail (method != NULL, NULL);
+  g_return_val_if_fail (g_dbus_is_member_name (method), NULL);
   g_return_val_if_fail (interface == NULL || g_dbus_is_interface_name (interface), NULL);
 
   message = g_dbus_message_new ();
@@ -127,6 +146,16 @@ g_dbus_message_new_method_call (const gchar *name,
   return message;
 }
 
+/**
+ * g_dbus_message_new_signal:
+ * @path: A valid object path.
+ * @interface: A valid D-Bus interface name or %NULL.
+ * @signal: A valid signal name.
+ *
+ * Creates a new #GDBusMessage for a signal emission.
+ *
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new_signal (const gchar  *path,
                            const gchar  *interface,
@@ -135,7 +164,7 @@ g_dbus_message_new_signal (const gchar  *path,
   GDBusMessage *message;
 
   g_return_val_if_fail (g_variant_is_object_path (path), NULL);
-  g_return_val_if_fail (signal != NULL, NULL);
+  g_return_val_if_fail (g_dbus_is_member_name (signal), NULL);
   g_return_val_if_fail (interface == NULL || g_dbus_is_interface_name (interface), NULL);
 
   message = g_dbus_message_new ();
@@ -152,6 +181,15 @@ g_dbus_message_new_signal (const gchar  *path,
 }
 
 
+/**
+ * g_dbus_message_new_method_reply:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+ * create a reply message to.
+ *
+ * Creates a new #GDBusMessage that is a reply to @method_call_message.
+ *
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new_method_reply (GDBusMessage *method_call_message)
 {
@@ -174,6 +212,17 @@ g_dbus_message_new_method_reply (GDBusMessage *method_call_message)
   return message;
 }
 
+/**
+ * g_dbus_message_new_method_error:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
+ * create a reply message to.
+ * @error_name: A valid D-Bus error name.
+ * @error_message: The D-Bus error message.
+ *
+ * Creates a new #GDBusMessage that is an error reply to @method_call_message.
+ *
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new_method_error (GDBusMessage  *method_call_message,
                                  const gchar   *error_name,
@@ -185,7 +234,7 @@ g_dbus_message_new_method_error (GDBusMessage  *method_call_message,
   g_return_val_if_fail (G_IS_DBUS_MESSAGE (method_call_message), NULL);
   g_return_val_if_fail (g_dbus_message_get_type (method_call_message) == G_DBUS_MESSAGE_TYPE_METHOD_CALL, NULL);
   g_return_val_if_fail (g_dbus_message_get_serial (method_call_message) != 0, NULL);
-  g_return_val_if_fail (error_name != NULL && g_dbus_is_name (error_name), NULL);
+  g_return_val_if_fail (g_dbus_is_name (error_name), NULL);
   g_return_val_if_fail (error_message != NULL, NULL);
 
   message = g_dbus_message_new ();
@@ -205,6 +254,16 @@ g_dbus_message_new_method_error (GDBusMessage  *method_call_message,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/* TODO: need GI annotations to specify that any guchar value goes for the type */
+
+/**
+ * g_dbus_message_get_type:
+ * @message: A #GDBusMessage.
+ *
+ * Gets the type of @message.
+ *
+ * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+ */
 GDBusMessageType
 g_dbus_message_get_type (GDBusMessage  *message)
 {
@@ -212,16 +271,34 @@ g_dbus_message_get_type (GDBusMessage  *message)
   return message->priv->type;
 }
 
+/**
+ * g_dbus_message_set_type:
+ * @message: A #GDBusMessage.
+ * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+ *
+ * Sets @message to be of @type.
+ */
 void
 g_dbus_message_set_type (GDBusMessage      *message,
                          GDBusMessageType   type)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (type >=0 && type < 256);
   message->priv->type = type;
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/* TODO: need GI annotations to specify that any guchar value goes for flags */
+
+/**
+ * g_dbus_message_get_flags:
+ * @message: A #GDBusMessage.
+ *
+ * Gets the flags for @message.
+ *
+ * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
+ */
 GDBusMessageFlags
 g_dbus_message_get_flags (GDBusMessage  *message)
 {
@@ -229,16 +306,33 @@ g_dbus_message_get_flags (GDBusMessage  *message)
   return message->priv->flags;
 }
 
+/**
+ * g_dbus_message_set_flags:
+ * @message: A #GDBusMessage.
+ * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
+ * enumeration bitwise ORed together).
+ *
+ * Sets the flags to set on @message.
+ */
 void
 g_dbus_message_set_flags (GDBusMessage       *message,
                           GDBusMessageFlags   flags)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (flags >=0 && flags < 256);
   message->priv->flags = flags;
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_serial:
+ * @message: A #GDBusMessage.
+ *
+ * Gets the serial for @message.
+ *
+ * Returns: A #guint32.
+ */
 guint32
 g_dbus_message_get_serial (GDBusMessage *message)
 {
@@ -246,6 +340,13 @@ g_dbus_message_get_serial (GDBusMessage *message)
   return message->priv->serial;
 }
 
+/**
+ * g_dbus_message_set_serial:
+ * @message: A #GDBusMessage.
+ * @serial: A #guint32.
+ *
+ * Sets the serial for @message.
+ */
 void
 g_dbus_message_set_serial (GDBusMessage  *message,
                            guint32        serial)
@@ -256,20 +357,44 @@ g_dbus_message_set_serial (GDBusMessage  *message,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/* TODO: need GI annotations to specify that any guchar value goes for header_field */
+
+/**
+ * g_dbus_message_get_header:
+ * @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+ *
+ * Gets a header field on @message.
+ *
+ * Returns: A #GVariant with the value if the header was found, %NULL
+ * otherwise. Do not free, it is owned by @message.
+ */
 GVariant *
 g_dbus_message_get_header (GDBusMessage             *message,
                            GDBusMessageHeaderField   header_field)
 {
   g_return_val_if_fail (G_IS_DBUS_MESSAGE (message), NULL);
+  g_return_val_if_fail (header_field >=0 && header_field < 256, NULL);
   return g_hash_table_lookup (message->priv->headers, GUINT_TO_POINTER (header_field));
 }
 
+/**
+ * g_dbus_message_set_header:
+ * @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+ * @value: A #GVariant to set the header field or %NULL to clear the header field.
+ *
+ * Sets a header field on @message.
+ *
+ * If @value is floating, @message assumes ownership of @value.
+ */
 void
 g_dbus_message_set_header (GDBusMessage             *message,
                            GDBusMessageHeaderField   header_field,
                            GVariant                 *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (header_field >=0 && header_field < 256);
   if (value == NULL)
     {
       g_hash_table_remove (message->priv->headers, GUINT_TO_POINTER (header_field));
@@ -280,11 +405,21 @@ g_dbus_message_set_header (GDBusMessage             *message,
     }
 }
 
-GDBusMessageHeaderField *
+/**
+ * g_dbus_message_get_header_fields:
+ * @message: A #GDBusMessage.
+ *
+ * Gets an array of all header fields on @message that are set.
+ *
+ * Returns: An array of header fields terminated by
+ * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID.  Each element is a
+ * #guchar. Free with g_free().
+ */
+guchar *
 g_dbus_message_get_header_fields (GDBusMessage  *message)
 {
   GList *keys;
-  GDBusMessageHeaderField *ret;
+  guchar *ret;
   guint num_keys;
   GList *l;
   guint n;
@@ -293,17 +428,26 @@ g_dbus_message_get_header_fields (GDBusMessage  *message)
 
   keys = g_hash_table_get_keys (message->priv->headers);
   num_keys = g_list_length (keys);
-  ret = g_new (GDBusMessageHeaderField, num_keys + 1);
+  ret = g_new (guchar, num_keys + 1);
   for (l = keys, n = 0; l != NULL; l = l->next, n++)
     ret[n] = GPOINTER_TO_UINT (l->data);
   g_assert (n == num_keys);
   ret[n] = G_DBUS_MESSAGE_HEADER_FIELD_INVALID;
+  g_list_free (keys);
 
   return ret;
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_body:
+ * @message: A #GDBusMessage.
+ *
+ * Gets the body of a message.
+ *
+ * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
+ */
 GVariant *
 g_dbus_message_get_body (GDBusMessage  *message)
 {
@@ -311,11 +455,24 @@ g_dbus_message_get_body (GDBusMessage  *message)
   return message->priv->body;
 }
 
+/**
+ * g_dbus_message_set_body:
+ * @message: A #GDBusMessage.
+ * @body: Either %NULL or a #GVariant that is a tuple.
+ *
+ * Sets the body @message. As a side-effect the
+ * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
+ * type string of @body (or cleared if @body is %NULL).
+ *
+ * If @body is floating, @message assumes ownership of @body.
+ */
 void
 g_dbus_message_set_body (GDBusMessage  *message,
                          GVariant      *body)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail ((body == NULL) || g_variant_is_of_type (body, G_VARIANT_TYPE_TUPLE));
+
   if (message->priv->body != NULL)
     g_variant_unref (message->priv->body);
   if (body == NULL)
@@ -343,6 +500,17 @@ g_dbus_message_set_body (GDBusMessage  *message,
 /* ---------------------------------------------------------------------------------------------------- */
 
 #ifdef G_OS_UNIX
+/**
+ * g_dbus_message_get_unix_fd_list:
+ * @message: A #GDBusMessage.
+ *
+ * Gets the UNIX file descriptors associated with @message, if any.
+ *
+ * This method is only available on UNIX.
+ *
+ * Returns: A #GUnixFDList or %NULL if no file descriptors are
+ * associated. Do not free, this object is owned by @message.
+ */
 GUnixFDList *
 g_dbus_message_get_unix_fd_list (GDBusMessage  *message)
 {
@@ -350,11 +518,24 @@ g_dbus_message_get_unix_fd_list (GDBusMessage  *message)
   return message->priv->fd_list;
 }
 
+/**
+ * g_dbus_message_set_unix_fd_list:
+ * @message: A #GDBusMessage.
+ * @fd_list: A #GDUnixFDList or %NULL.
+ *
+ * Sets the UNIX file descriptors associated with @message. As a
+ * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
+ * field is set to the number of fds in @fd_list (or cleared if
+ * @fd_list is %NULL).
+ *
+ * This method is only available on UNIX.
+ */
 void
 g_dbus_message_set_unix_fd_list (GDBusMessage  *message,
                                  GUnixFDList   *fd_list)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (fd_list == NULL || G_IS_UNIX_FD_LIST (fd_list));
   if (message->priv->fd_list != NULL)
     g_object_unref (message->priv->fd_list);
   if (fd_list != NULL)
@@ -757,6 +938,20 @@ parse_value_from_blob (GMemoryInputStream    *mis,
 /* ---------------------------------------------------------------------------------------------------- */
 
 /* message_header must be at least 16 bytes */
+
+/**
+ * g_dbus_message_bytes_needed:
+ * @blob: A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob (must be at least 16).
+ * @error: Return location for error or %NULL.
+ *
+ * Utility function to calculate how many bytes are needed to
+ * completely deserialize the D-Bus message stored at @blob.
+ *
+ * Returns: Number of bytes needed or -1 if @error is set (e.g. if
+ * @blob contains invalid data or not enough data is available to
+ * determine the size).
+ */
 gssize
 g_dbus_message_bytes_needed (guchar  *blob,
                              gsize    blob_len,
@@ -806,6 +1001,17 @@ g_dbus_message_bytes_needed (guchar  *blob,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_new_from_blob:
+ * @blob: A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob.
+ * @error: Return location for error or %NULL.
+ *
+ * Creates a new #GDBusMessage from the data stored at @blob.
+ *
+ * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
+ * g_object_unref().
+ */
 GDBusMessage *
 g_dbus_message_new_from_blob (guchar    *blob,
                               gsize      blob_len,
@@ -1236,6 +1442,17 @@ append_body_to_blob (GVariant             *value,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_to_blob:
+ * @message: A #GDBusMessage.
+ * @out_size: Return location for size of generated blob.
+ * @error: Return location for error.
+ *
+ * Serializes @message to a blob.
+ *
+ * Returns: A pointer to a valid binary D-Bus message of @out_size bytes
+ * generated by @message or %NULL if @error is set. Free with g_free().
+ */
 guchar *
 g_dbus_message_to_blob (GDBusMessage   *message,
                         gsize          *out_size,
@@ -1493,6 +1710,14 @@ set_signature_header (GDBusMessage             *message,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_reply_serial:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ *
+ * Returns: The value.
+ */
 guint32
 g_dbus_message_get_reply_serial (GDBusMessage  *message)
 {
@@ -1500,6 +1725,13 @@ g_dbus_message_get_reply_serial (GDBusMessage  *message)
   return get_uint32_header (message, G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL);
 }
 
+/**
+ * g_dbus_message_set_reply_serial:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ */
 void
 g_dbus_message_set_reply_serial (GDBusMessage  *message,
                                  guint32        value)
@@ -1510,6 +1742,14 @@ g_dbus_message_set_reply_serial (GDBusMessage  *message,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_interface:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_interface (GDBusMessage  *message)
 {
@@ -1517,16 +1757,32 @@ g_dbus_message_get_interface (GDBusMessage  *message)
   return get_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE);
 }
 
+/**
+ * g_dbus_message_set_interface:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ */
 void
 g_dbus_message_set_interface (GDBusMessage  *message,
                               const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_dbus_is_interface_name (value));
   set_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_member:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_member (GDBusMessage  *message)
 {
@@ -1534,16 +1790,32 @@ g_dbus_message_get_member (GDBusMessage  *message)
   return get_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_MEMBER);
 }
 
+/**
+ * g_dbus_message_set_member:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ */
 void
 g_dbus_message_set_member (GDBusMessage  *message,
                            const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_dbus_is_member_name (value));
   set_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_MEMBER, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_path:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_path (GDBusMessage  *message)
 {
@@ -1551,16 +1823,32 @@ g_dbus_message_get_path (GDBusMessage  *message)
   return get_object_path_header (message, G_DBUS_MESSAGE_HEADER_FIELD_PATH);
 }
 
+/**
+ * g_dbus_message_set_path:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ */
 void
 g_dbus_message_set_path (GDBusMessage  *message,
                          const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_variant_is_object_path (value));
   set_object_path_header (message, G_DBUS_MESSAGE_HEADER_FIELD_PATH, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_sender:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_sender (GDBusMessage *message)
 {
@@ -1568,16 +1856,32 @@ g_dbus_message_get_sender (GDBusMessage *message)
   return get_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_SENDER);
 }
 
+/**
+ * g_dbus_message_set_sender:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ */
 void
 g_dbus_message_set_sender (GDBusMessage  *message,
                            const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_dbus_is_name (value));
   set_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_SENDER, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_destination:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_destination (GDBusMessage  *message)
 {
@@ -1585,16 +1889,32 @@ g_dbus_message_get_destination (GDBusMessage  *message)
   return get_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION);
 }
 
+/**
+ * g_dbus_message_set_destination:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ */
 void
 g_dbus_message_set_destination (GDBusMessage  *message,
                                 const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_dbus_is_name (value));
   set_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_error_name:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_error_name (GDBusMessage  *message)
 {
@@ -1602,16 +1922,32 @@ g_dbus_message_get_error_name (GDBusMessage  *message)
   return get_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME);
 }
 
+/**
+ * g_dbus_message_set_error_name:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ */
 void
 g_dbus_message_set_error_name (GDBusMessage  *message,
                                const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_dbus_is_interface_name (value));
   set_string_header (message, G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_signature:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ *
+ * Returns: The value.
+ */
 const gchar *
 g_dbus_message_get_signature (GDBusMessage  *message)
 {
@@ -1623,16 +1959,33 @@ g_dbus_message_get_signature (GDBusMessage  *message)
   return ret;
 }
 
+/**
+ * g_dbus_message_set_signature:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ */
 void
 g_dbus_message_set_signature (GDBusMessage  *message,
                               const gchar   *value)
 {
   g_return_if_fail (G_IS_DBUS_MESSAGE (message));
+  g_return_if_fail (value == NULL || g_variant_is_signature (value));
   set_signature_header (message, G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE, value);
 }
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_arg0:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience to get the first item in the body of @message.
+ *
+ * Returns: The string item or %NULL if the first item in the body of
+ * @message is not a string.
+ */
 const gchar *
 g_dbus_message_get_arg0 (GDBusMessage  *message)
 {
@@ -1655,6 +2008,14 @@ g_dbus_message_get_arg0 (GDBusMessage  *message)
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_get_num_unix_fds:
+ * @message: A #GDBusMessage.
+ *
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ *
+ * Returns: The value.
+ */
 guint32
 g_dbus_message_get_num_unix_fds (GDBusMessage *message)
 {
@@ -1662,6 +2023,13 @@ g_dbus_message_get_num_unix_fds (GDBusMessage *message)
   return get_uint32_header (message, G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS);
 }
 
+/**
+ * g_dbus_message_set_num_unix_fds:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ */
 void
 g_dbus_message_set_num_unix_fds (GDBusMessage  *message,
                                  guint32        value)
@@ -1672,6 +2040,21 @@ g_dbus_message_set_num_unix_fds (GDBusMessage  *message,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * g_dbus_message_to_gerror:
+ * @message: A #GDBusMessage.
+ * @error: The #GError to set.
+ *
+ * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
+ * nothing and returns %FALSE.
+ *
+ * Otherwise this method encodes the error in @message as a #GError
+ * using g_dbus_error_set_dbus_error() using the information in the
+ * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
+ * well as the first string item in @message's body.
+ *
+ * Returns: %TRUE if @error was set, %FALSE otherwise.
+ */
 gboolean
 g_dbus_message_to_gerror (GDBusMessage   *message,
                           GError        **error)
diff --git a/gdbus/gdbusmessage.h b/gdbus/gdbusmessage.h
index 2ca6618..5890d3d 100644
--- a/gdbus/gdbusmessage.h
+++ b/gdbus/gdbusmessage.h
@@ -92,7 +92,7 @@ GVariant                 *g_dbus_message_get_header         (GDBusMessage
 void                      g_dbus_message_set_header         (GDBusMessage             *message,
                                                              GDBusMessageHeaderField   header_field,
                                                              GVariant                 *value);
-GDBusMessageHeaderField  *g_dbus_message_get_header_fields  (GDBusMessage             *message);
+guchar                   *g_dbus_message_get_header_fields  (GDBusMessage             *message);
 GVariant                 *g_dbus_message_get_body           (GDBusMessage             *message);
 void                      g_dbus_message_set_body           (GDBusMessage             *message,
                                                              GVariant                 *body);