[evolution-data-server/wip/tintou/camel-mime-message-doc] [Camel] Add more documentation and annotations to CamelMimeMessage

[Corentin Noël <corentinnoel src gnome org>]

commit ff51dd76a92fefb9020624b62b9bf7e04169fa92
Author: Corentin Noël <corentin elementary io>
Date:   Thu Feb 7 11:01:55 2019 +0100

    [Camel] Add more documentation and annotations to CamelMimeMessage

 src/camel/camel-mime-message.c | 77 +++++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 24 deletions(-)
---
diff --git a/src/camel/camel-mime-message.c b/src/camel/camel-mime-message.c
index eb9173f84..bd83f2ee2 100644
--- a/src/camel/camel-mime-message.c
+++ b/src/camel/camel-mime-message.c
@@ -447,10 +447,18 @@ camel_mime_message_new (void)
 /**
  * camel_mime_message_set_date:
  * @message: a #CamelMimeMessage object
- * @date: a time_t date
- * @offset: an offset from GMT
+ * @date: a time_t date or #CAMEL_MESSAGE_DATE_CURRENT to use the current local
+ * date and time.
+ * @offset: an offset from UTC in decimal number using the +HHMM format (for
+ * instance an offset of -10:45 is -1045). If @date set to
+ * #CAMEL_MESSAGE_DATE_CURRENT, this parameter is ignored.
  *
  * Set the date on a message.
+ *
+ * In most cases, this is used to set the current date:
+ * |[<!-- language="C" -->
+ * camel_mime_message_set_date (message, CAMEL_MESSAGE_DATE_CURRENT, 0);
+ * ]|
  **/
 void
 camel_mime_message_set_date (CamelMimeMessage *message,
@@ -480,9 +488,10 @@ camel_mime_message_set_date (CamelMimeMessage *message,
 /**
  * camel_mime_message_get_date:
  * @message: a #CamelMimeMessage object
- * @offset: output for the GMT offset
+ * @offset: (out): output for the UTC offset
  *
- * Get the date and GMT offset of a message.
+ * Get the date and UTC offset of a message.
+ * See camel_mime_message_set_date() for information about the @offset format.
  *
  * Returns: the date of the message
  **/
@@ -499,9 +508,10 @@ camel_mime_message_get_date (CamelMimeMessage *msg,
 /**
  * camel_mime_message_get_date_received:
  * @message: a #CamelMimeMessage object
- * @offset: output for the GMT offset
+ * @offset: (out): output for the UTC offset
  *
- * Get the received date and GMT offset of a message.
+ * Get the received date and UTC offset of a message.
+ * See camel_mime_message_set_date() for information about the @offset format.
  *
  * Returns: the received date of the message
  **/
@@ -530,7 +540,8 @@ camel_mime_message_get_date_received (CamelMimeMessage *msg,
 /**
  * camel_mime_message_set_message_id:
  * @message: a #CamelMimeMessage object
- * @message_id: id of the message
+ * @message_id: (nullable): id of the message, or %NULL to generate a new one
+ * using the from address.
  *
  * Set the message-id on a message.
  **/
@@ -574,7 +585,7 @@ camel_mime_message_set_message_id (CamelMimeMessage *mime_message,
  *
  * Get the message-id of a message.
  *
- * Returns: the message-id of a message
+ * Returns: (nullable): the message-id of a message
  **/
 const gchar *
 camel_mime_message_get_message_id (CamelMimeMessage *mime_message)
@@ -589,7 +600,7 @@ camel_mime_message_get_message_id (CamelMimeMessage *mime_message)
 /**
  * camel_mime_message_set_reply_to:
  * @message: a #CamelMimeMessage object
- * @reply_to: a #CamelInternetAddress object
+ * @reply_to: (nullable): a #CamelInternetAddress object
  *
  * Set the Reply-To of a message.
  **/
@@ -620,7 +631,7 @@ camel_mime_message_set_reply_to (CamelMimeMessage *msg,
  *
  * Get the Reply-To of a message.
  *
- * Returns: (transfer none): the Reply-To address of the message
+ * Returns: (transfer none) (nullable): the Reply-To address of the message
  **/
 CamelInternetAddress *
 camel_mime_message_get_reply_to (CamelMimeMessage *mime_message)
@@ -637,7 +648,7 @@ camel_mime_message_get_reply_to (CamelMimeMessage *mime_message)
 /**
  * camel_mime_message_set_subject:
  * @message: a #CamelMimeMessage object
- * @subject: UTF-8 message subject
+ * @subject: (nullable): UTF-8 message subject
  *
  * Set the subject text of a message.
  **/
@@ -669,7 +680,7 @@ camel_mime_message_set_subject (CamelMimeMessage *message,
  *
  * Get the UTF-8 subject text of a message.
  *
- * Returns: the message subject
+ * Returns: (nullable): the message subject
  **/
 const gchar *
 camel_mime_message_get_subject (CamelMimeMessage *mime_message)
@@ -688,7 +699,7 @@ camel_mime_message_get_subject (CamelMimeMessage *mime_message)
 /**
  * camel_mime_message_set_from:
  * @message: a #CamelMimeMessage object
- * @from: a #CamelInternetAddress object
+ * @from: (nullable): a #CamelInternetAddress object
  *
  * Set the from address of a message.
  **/
@@ -719,7 +730,7 @@ camel_mime_message_set_from (CamelMimeMessage *msg,
  *
  * Get the from address of a message.
  *
- * Returns: (transfer none): the from address of the message
+ * Returns: (transfer none) (nullable): the from address of the message
  **/
 CamelInternetAddress *
 camel_mime_message_get_from (CamelMimeMessage *mime_message)
@@ -736,8 +747,10 @@ camel_mime_message_get_from (CamelMimeMessage *mime_message)
 /**
  * camel_mime_message_set_recipients:
  * @message: a #CamelMimeMessage object
- * @type: recipient type (one of #CAMEL_RECIPIENT_TYPE_TO, #CAMEL_RECIPIENT_TYPE_CC, or 
#CAMEL_RECIPIENT_TYPE_BCC)
- * @recipients: a #CamelInternetAddress with the recipient addresses set
+ * @type: recipient type (one of #CAMEL_RECIPIENT_TYPE_TO,
+ * #CAMEL_RECIPIENT_TYPE_CC, or #CAMEL_RECIPIENT_TYPE_BCC)
+ * @recipients: (nullable): a #CamelInternetAddress with the recipient addresses
+ * set or %NULL to remove the already defined one.
  *
  * Set the recipients of a message.
  **/
@@ -779,7 +792,7 @@ camel_mime_message_set_recipients (CamelMimeMessage *mime_message,
  *
  * Get the message recipients of a specified type.
  *
- * Returns: (transfer none): the requested recipients
+ * Returns: (transfer none) (nullable): the requested recipients
  **/
 CamelInternetAddress *
 camel_mime_message_get_recipients (CamelMimeMessage *mime_message,
@@ -790,42 +803,57 @@ camel_mime_message_get_recipients (CamelMimeMessage *mime_message,
        return g_hash_table_lookup (mime_message->priv->recipients, type);
 }
 
+/**
+ * camel_mime_message_set_source:
+ * @message: a #CamelMimeMessage object
+ * @source_uid: (nullable): the uid of the source
+ *
+ * Set the source uid of the message.
+ **/
 void
-camel_mime_message_set_source (CamelMimeMessage *mime_message,
+camel_mime_message_set_source (CamelMimeMessage *message,
                                const gchar *source_uid)
 {
        CamelMedium *medium;
        const gchar *name;
 
-       g_return_if_fail (CAMEL_IS_MIME_MESSAGE (mime_message));
+       g_return_if_fail (CAMEL_IS_MIME_MESSAGE (message));
 
        /* FIXME The header name is Evolution-specific.
         *       "X" header prefix should be configurable
         *       somehow, perhaps through CamelSession. */
 
        name = "X-Evolution-Source";
-       medium = CAMEL_MEDIUM (mime_message);
+       medium = CAMEL_MEDIUM (message);
 
        camel_medium_remove_header (medium, name);
        if (source_uid != NULL)
                camel_medium_add_header (medium, name, source_uid);
 }
 
+/**
+ * camel_mime_message_get_source:
+ * @message: a #CamelMimeMessage object
+ *
+ * Get the source uid of the message.
+ *
+ * Returns: (nullable): the uid of the source
+ **/
 const gchar *
-camel_mime_message_get_source (CamelMimeMessage *mime_message)
+camel_mime_message_get_source (CamelMimeMessage *message)
 {
        CamelMedium *medium;
        const gchar *name;
        const gchar *src;
 
-       g_return_val_if_fail (CAMEL_IS_MIME_MESSAGE (mime_message), NULL);
+       g_return_val_if_fail (CAMEL_IS_MIME_MESSAGE (message), NULL);
 
        /* FIXME The header name is Evolution-specific.
         *       "X" header prefix should be configurable
         *       somehow, perhaps through CamelSession. */
 
        name = "X-Evolution-Source";
-       medium = CAMEL_MEDIUM (mime_message);
+       medium = CAMEL_MEDIUM (message);
 
        src = camel_medium_get_header (medium, name);
        if (src != NULL) {
@@ -1189,7 +1217,8 @@ check_content_id (CamelMimeMessage *message,
  *
  * Get a MIME part by id from a message.
  *
- * Returns: (transfer none): the MIME part with the requested id or %NULL if not found
+ * Returns: (transfer none) (nullable): the MIME part with the requested id,
+ * or %NULL if not found
  **/
 CamelMimePart *
 camel_mime_message_get_part_by_content_id (CamelMimeMessage *message,