[gmime] introspection: add many missing annotations

From: Jeffrey Stedfast <fejj src gnome org>
To: commits-list gnome org
Cc:
Subject: [gmime] introspection: add many missing annotations
Date: Sat, 29 Jun 2013 16:36:02 +0000 (UTC)
commit 54d523df343b888368a7520f1ddee7d0f7c8a2a3
Author: Evan Nemerson <evan coeus-group com>
Date:   Wed Jun 26 14:31:47 2013 -0700

    introspection: add many missing annotations
    
    These changes include most of the things g-ir-scanner warns about as
    well as some changes ported from Yorba's Vala bindings.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=703091

 gmime/GMime-2.6.metadata          |   10 +++++++---
 gmime/Makefile.am                 |    6 +++++-
 gmime/gmime-certificate.c         |    4 ++--
 gmime/gmime-charset.c             |    3 ++-
 gmime/gmime-charset.h             |    5 +++--
 gmime/gmime-crypto-context.c      |   17 ++++++++++-------
 gmime/gmime-data-wrapper.c        |    2 +-
 gmime/gmime-encodings.h           |    5 +++--
 gmime/gmime-filter.c              |   22 ++++++++++++----------
 gmime/gmime-filter.h              |    8 +++++---
 gmime/gmime-gpg-context.c         |    2 +-
 gmime/gmime-header.c              |    6 +++---
 gmime/gmime-iconv-utils.c         |    4 ++--
 gmime/gmime-iconv.c               |    6 +++---
 gmime/gmime-message-part.c        |    2 +-
 gmime/gmime-message-partial.c     |    7 ++++---
 gmime/gmime-message.c             |   22 ++++++++++++----------
 gmime/gmime-multipart-encrypted.c |    8 ++++----
 gmime/gmime-multipart-signed.c    |    7 ++++---
 gmime/gmime-multipart.c           |   17 +++++++++--------
 gmime/gmime-object.c              |   10 ++++++----
 gmime/gmime-param.c               |    1 -
 gmime/gmime-param.h               |    1 -
 gmime/gmime-parser.c              |    5 +++--
 gmime/gmime-part-iter.c           |   10 +++++-----
 gmime/gmime-part.c                |    3 ++-
 gmime/gmime-pkcs7-context.c       |    2 +-
 gmime/gmime-signature.c           |    6 +++---
 gmime/gmime-stream-gio.c          |    5 +++--
 gmime/gmime-stream-mem.c          |    4 ++--
 gmime/gmime-stream.c              |    5 +++--
 gmime/gmime-utils.c               |    5 +++--
 gmime/internet-address.c          |   11 ++++++-----
 33 files changed, 130 insertions(+), 101 deletions(-)
---
diff --git a/gmime/GMime-2.6.metadata b/gmime/GMime-2.6.metadata
index 4f3da25..f418967 100644
--- a/gmime/GMime-2.6.metadata
+++ b/gmime/GMime-2.6.metadata
@@ -16,8 +16,12 @@ Object
 Parser
   .construct_message nullable
 
-// G-I doesn't allow non-GObject inheritance
+// G-I doesn't have a time_t type
 utils_header_decode_date type="time_t"
 
-// g_mime_utils_header_decode_phrase transfer_ownership="1"
-// g_mime_utils_header_decode_text transfer_ownership="1"
\ No newline at end of file
+// G-I doesn't support annotations on fields (bug #561619)
+Filter
+  .backbuf type="uint8[]" array_length_field="backsize"
+  .outreal type="uint8[]"
+       .outbuf type="unowned uint8[]" array_length_field="outsize"
+  .outptr type="unowned uint8[]"
diff --git a/gmime/Makefile.am b/gmime/Makefile.am
index 5184a68..28a6e66 100644
--- a/gmime/Makefile.am
+++ b/gmime/Makefile.am
@@ -183,7 +183,11 @@ GMime_2_6_gir_CFLAGS = $(INCLUDES)
 GMime_2_6_gir_LIBS = libgmime-2.6.la
 GMime_2_6_gir_FILES = $(gmimeinclude_HEADERS) $(libgmime_2_6_la_SOURCES)
 GMime_2_6_gir_EXPORT_PACKAGES = gmime-2.6
-GMime_2_6_gir_SCANNERFLAGS = --c-include="gmime/gmime.h" --accept-unprefixed
+GMime_2_6_gir_SCANNERFLAGS = \
+       --c-include="gmime/gmime.h" \
+       --accept-unprefixed \
+       --symbol-prefix "gmime_" \
+       --symbol-prefix "g_mime_"
 INTROSPECTION_GIRS += GMime-2.6.gir
 
 girdir = $(datadir)/gir-1.0
diff --git a/gmime/gmime-certificate.c b/gmime/gmime-certificate.c
index 6efd7f2..ba45770 100644
--- a/gmime/gmime-certificate.c
+++ b/gmime/gmime-certificate.c
@@ -790,8 +790,8 @@ g_mime_certificate_list_index_of (GMimeCertificateList *list, GMimeCertificate *
  *
  * Gets the #GMimeCertificate at the specified index.
  *
- * Returns: the #GMimeCertificate at the specified index or %NULL if
- * the index is out of range.
+ * Returns: (transfer full): the #GMimeCertificate at the specified
+ * index or %NULL if the index is out of range.
  **/
 GMimeCertificate *
 g_mime_certificate_list_get_certificate (GMimeCertificateList *list, int index)
diff --git a/gmime/gmime-charset.c b/gmime/gmime-charset.c
index f170f89..42b0232 100644
--- a/gmime/gmime-charset.c
+++ b/gmime/gmime-charset.c
@@ -938,7 +938,8 @@ g_mime_set_user_charsets (const char **charsets)
  * Get the list of user-preferred charsets set with
  * g_mime_set_user_charsets().
  *
- * Returns: an array of user-set charsets or %NULL if none set.
+ * Returns: (array zero-terminated=1) (transfer none): an array of
+ * user-set charsets or %NULL if none set.
  **/
 const char **
 g_mime_user_charsets (void)
diff --git a/gmime/gmime-charset.h b/gmime/gmime-charset.h
index 5a0a21e..c830dfc 100644
--- a/gmime/gmime-charset.h
+++ b/gmime/gmime-charset.h
@@ -45,6 +45,7 @@ const char *g_mime_charset_locale_name (void);
 
 const char *g_mime_charset_iso_to_windows (const char *isocharset);
 
+typedef struct _GMimeCharset GMimeCharset;
 
 /**
  * GMimeCharset:
@@ -53,10 +54,10 @@ const char *g_mime_charset_iso_to_windows (const char *isocharset);
  *
  * State used by g_mime_charset_best() and g_mime_charset_best_name().
  **/
-typedef struct _GMimeCharset {
+struct _GMimeCharset {
        unsigned int mask;
        unsigned int level;
-} GMimeCharset;
+};
 
 void g_mime_charset_init (GMimeCharset *charset);
 void g_mime_charset_step (GMimeCharset *charset, const char *inbuf, size_t inlen);
diff --git a/gmime/gmime-crypto-context.c b/gmime/gmime-crypto-context.c
index ae98090..2a1fa34 100644
--- a/gmime/gmime-crypto-context.c
+++ b/gmime/gmime-crypto-context.c
@@ -357,8 +357,8 @@ crypto_verify (GMimeCryptoContext *ctx, GMimeDigestAlgo digest, GMimeStream *ist
  * @sigstream is assumed to be the signature stream and is used to
  * verify the integirity of the @istream.
  *
- * Returns: a #GMimeSignatureList object containing the status of each
- * signature or %NULL on error.
+ * Returns: (transfer full): a #GMimeSignatureList object containing
+ * the status of each signature or %NULL on error.
  **/
 GMimeSignatureList *
 g_mime_crypto_context_verify (GMimeCryptoContext *ctx, GMimeDigestAlgo digest, GMimeStream *istream,
@@ -388,7 +388,8 @@ crypto_encrypt (GMimeCryptoContext *ctx, gboolean sign, const char *userid, GMim
  * @sign: sign as well as encrypt
  * @userid: key id (or email address) to use when signing (assuming @sign is %TRUE)
  * @digest: digest algorithm to use when signing
- * @recipients: an array of recipient key ids and/or email addresses
+ * @recipients: (element-type utf8): an array of recipient key ids
+ *   and/or email addresses
  * @istream: cleartext input stream
  * @ostream: ciphertext output stream
  * @err: a #GError
@@ -439,7 +440,8 @@ crypto_decrypt (GMimeCryptoContext *ctx, GMimeStream *istream,
  * certificates, one for each recipient, that the original encrypted stream
  * was encrypted to.
  *
- * Returns: a #GMimeDecryptResult on success or %NULL on error.
+ * Returns: (transfer full): a #GMimeDecryptResult on success or %NULL
+ * on error.
  **/
 GMimeDecryptResult *
 g_mime_crypto_context_decrypt (GMimeCryptoContext *ctx, GMimeStream *istream,
@@ -498,7 +500,7 @@ crypto_export_keys (GMimeCryptoContext *ctx, GPtrArray *keys,
 /**
  * g_mime_crypto_context_export_keys:
  * @ctx: a #GMimeCryptoContext
- * @keys: an array of key ids
+ * @keys: (element-type utf8): an array of key ids
  * @ostream: output stream
  * @err: a #GError
  *
@@ -630,7 +632,7 @@ g_mime_decrypt_result_set_recipients (GMimeDecryptResult *result, GMimeCertifica
  *
  * Gets the list of certificates that the stream had been encrypted to.
  *
- * Returns: a #GMimeCertificateList.
+ * Returns: (transfer none): a #GMimeCertificateList.
  **/
 GMimeCertificateList *
 g_mime_decrypt_result_get_recipients (GMimeDecryptResult *result)
@@ -673,7 +675,8 @@ g_mime_decrypt_result_set_signatures (GMimeDecryptResult *result, GMimeSignature
  *
  * Gets a list of signatures if the encrypted stream had also been signed.
  *
- * Returns: a #GMimeSignatureList or %NULL if the stream was not signed.
+ * Returns: (transfer none): a #GMimeSignatureList or %NULL if the
+ * stream was not signed.
  **/
 GMimeSignatureList *
 g_mime_decrypt_result_get_signatures (GMimeDecryptResult *result)
diff --git a/gmime/gmime-data-wrapper.c b/gmime/gmime-data-wrapper.c
index 4adb52b..6f5b780 100644
--- a/gmime/gmime-data-wrapper.c
+++ b/gmime/gmime-data-wrapper.c
@@ -184,7 +184,7 @@ g_mime_data_wrapper_set_stream (GMimeDataWrapper *wrapper, GMimeStream *stream)
  *
  * Gets a reference to the stream wrapped by @wrapper.
  *
- * Returns: a reference to the internal stream.
+ * Returns: (transfer none): a reference to the internal stream.
  **/
 GMimeStream *
 g_mime_data_wrapper_get_stream (GMimeDataWrapper *wrapper)
diff --git a/gmime/gmime-encodings.h b/gmime/gmime-encodings.h
index 649ae42..b98c5a7 100644
--- a/gmime/gmime-encodings.h
+++ b/gmime/gmime-encodings.h
@@ -138,6 +138,7 @@ const char *g_mime_content_encoding_to_string (GMimeContentEncoding encoding);
 #define GMIME_UUDECODE_STATE_END    (1 << 17)
 #define GMIME_UUDECODE_STATE_MASK   (GMIME_UUDECODE_STATE_BEGIN | GMIME_UUDECODE_STATE_END)
 
+typedef struct _GMimeEncoding GMimeEncoding;
 
 /**
  * GMimeEncoding:
@@ -149,13 +150,13 @@ const char *g_mime_content_encoding_to_string (GMimeContentEncoding encoding);
  *
  * A context used for encoding or decoding data.
  **/
-typedef struct _GMimeEncoding {
+struct _GMimeEncoding {
        GMimeContentEncoding encoding;
        unsigned char uubuf[60];
        gboolean encode;
        guint32 save;
        int state;
-} GMimeEncoding;
+};
 
 
 void g_mime_encoding_init_encode (GMimeEncoding *state, GMimeContentEncoding encoding);
diff --git a/gmime/gmime-filter.c b/gmime/gmime-filter.c
index 3d3d416..7b3e73a 100644
--- a/gmime/gmime-filter.c
+++ b/gmime/gmime-filter.c
@@ -145,7 +145,7 @@ filter_copy (GMimeFilter *filter)
  *
  * Copies @filter into a new GMimeFilter object.
  *
- * Returns: a duplicate of @filter.
+ * Returns: (transfer full): a duplicate of @filter.
  **/
 GMimeFilter *
 g_mime_filter_copy (GMimeFilter *filter)
@@ -206,12 +206,13 @@ filter_filter (GMimeFilter *filter, char *inbuf, size_t inlen, size_t prespace,
 /**
  * g_mime_filter_filter:
  * @filter: filter
- * @inbuf: input buffer
+ * @inbuf: (array length=inlen) (element-type guint8): input buffer
  * @inlen: input buffer length
  * @prespace: prespace buffer length
- * @outbuf: pointer to output buffer
- * @outlen: pointer to output length
- * @outprespace: pointer to output prespace buffer length
+ * @outbuf: (out) (array length=outlen) (element-type guint8) (transfer none):
+ *   pointer to output buffer
+ * @outlen: (out): pointer to output length
+ * @outprespace: (out): pointer to output prespace buffer length
  *
  * Filters the input data and writes it to @out.
  **/
@@ -237,12 +238,13 @@ filter_complete (GMimeFilter *filter, char *inbuf, size_t inlen, size_t prespace
 /**
  * g_mime_filter_complete:
  * @filter: filter
- * @inbuf: input buffer
+ * @inbuf: (array length=inlen) (element-type guint8): input buffer
  * @inlen: input buffer length
  * @prespace: prespace buffer length
- * @outbuf: pointer to output buffer
- * @outlen: pointer to output length
- * @outprespace: pointer to output prespace buffer length
+ * @outbuf: (out) (array length=outlen) (element-type guint8) (transfer none):
+ *   pointer to output buffer
+ * @outlen: (out): pointer to output length
+ * @outprespace: (out): pointer to output prespace buffer length
  *
  * Completes the filtering.
  **/
@@ -286,7 +288,7 @@ g_mime_filter_reset (GMimeFilter *filter)
 /**
  * g_mime_filter_backup:
  * @filter: filter
- * @data: data to backup
+ * @data: (array length=length) (element-type guint8): data to backup
  * @length: length of @data
  *
  * Sets number of bytes backed up on the input, new calls replace
diff --git a/gmime/gmime-filter.h b/gmime/gmime-filter.h
index 77031bf..e5e0be4 100644
--- a/gmime/gmime-filter.h
+++ b/gmime/gmime-filter.h
@@ -42,12 +42,14 @@ typedef struct _GMimeFilterClass GMimeFilterClass;
  * GMimeFilter:
  * @parent_object: parent #GObject
  * @priv: private state data
- * @outreal: real malloc'd buffer
- * @outbuf: first writable position allowed (outreal + outpre)
+ * @outreal: (array) (element-type guint8): real malloc'd buffer
+ * @outbuf: (array length=outsize) (element-type guint8): first
+ *   writable position allowed (outreal + outpre)
  * @outptr: current writale position
  * @outsize: current bytes in @outbuf
  * @outpre: current prespace of @outbuf
- * @backbuf: backup buffer
+ * @backbuf: (array length=backsize) (element-type guint8): backup
+ *   buffer
  * @backsize: backup buffer size
  * @backlen: number of bytes backed-up in @backbuf
  *
diff --git a/gmime/gmime-gpg-context.c b/gmime/gmime-gpg-context.c
index 6975b7a..4c99513 100644
--- a/gmime/gmime-gpg-context.c
+++ b/gmime/gmime-gpg-context.c
@@ -2192,7 +2192,7 @@ gpg_export_keys (GMimeCryptoContext *context, GPtrArray *keys, GMimeStream *ostr
  *
  * Creates a new gpg crypto context object.
  *
- * Returns: a new gpg crypto context object.
+ * Returns: (transfer full): a new gpg crypto context object.
  **/
 GMimeCryptoContext *
 g_mime_gpg_context_new (GMimePasswordRequestFunc request_passwd, const char *path)
diff --git a/gmime/gmime-header.c b/gmime/gmime-header.c
index 69ec551..f2dc703 100644
--- a/gmime/gmime-header.c
+++ b/gmime/gmime-header.c
@@ -801,7 +801,7 @@ g_mime_header_list_remove (GMimeHeaderList *headers, const char *name)
 /**
  * g_mime_header_list_get_iter:
  * @headers: a #GMimeHeaderList
- * @iter: a #GMimeHeaderIter
+ * @iter: (out): a #GMimeHeaderIter
  *
  * Initializes an iterator for traversing @headers.
  *
@@ -830,7 +830,7 @@ g_mime_header_list_get_iter (GMimeHeaderList *headers, GMimeHeaderIter *iter)
 /**
  * g_mime_header_list_foreach:
  * @headers: A #GMimeHeaderList
- * @func: function to be called for each header.
+ * @func: (scope call): function to be called for each header.
  * @user_data: User data to be passed to the func.
  *
  * Calls @func for each header name/value pair.
@@ -1015,7 +1015,7 @@ g_mime_header_list_set_stream (GMimeHeaderList *headers, GMimeStream *stream)
  *
  * Gets the raw stream representing @headers.
  *
- * Returns: a #GMimeStream if set or %NULL otherwise.
+ * Returns: (transfer none): a #GMimeStream if set or %NULL otherwise.
  **/
 GMimeStream *
 g_mime_header_list_get_stream (GMimeHeaderList *headers)
diff --git a/gmime/gmime-iconv-utils.c b/gmime/gmime-iconv-utils.c
index df108f0..9e83088 100644
--- a/gmime/gmime-iconv-utils.c
+++ b/gmime/gmime-iconv-utils.c
@@ -86,7 +86,7 @@ iconv_utils_init (void)
 
 
 /**
- * g_mime_iconv_strndup:
+ * g_mime_iconv_strndup: (skip)
  * @cd: conversion descriptor
  * @str: string in source charset
  * @n: number of bytes to convert
@@ -189,7 +189,7 @@ g_mime_iconv_strndup (iconv_t cd, const char *str, size_t n)
 
 
 /**
- * g_mime_iconv_strdup:
+ * g_mime_iconv_strdup: (skip)
  * @cd: conversion descriptor
  * @str: string in source charset
  *
diff --git a/gmime/gmime-iconv.c b/gmime/gmime-iconv.c
index 1d6f0c0..3deac78 100644
--- a/gmime/gmime-iconv.c
+++ b/gmime/gmime-iconv.c
@@ -93,7 +93,7 @@ static GStaticMutex iconv_cache_lock = G_STATIC_MUTEX_INIT;
 
 
 /**
- * iconv_cache_node_new:
+ * iconv_cache_node_new: (skip)
  * @key: cache key
  * @cd: iconv descriptor
  *
@@ -221,7 +221,7 @@ g_mime_iconv_init (void)
 
 
 /**
- * g_mime_iconv_open:
+ * g_mime_iconv_open: (skip)
  * @to: charset to convert to
  * @from: charset to convert from
  *
@@ -308,7 +308,7 @@ g_mime_iconv_open (const char *to, const char *from)
 
 
 /**
- * g_mime_iconv_close:
+ * g_mime_iconv_close: (skip)
  * @cd: iconv conversion descriptor
  *
  * Closes the iconv descriptor @cd.
diff --git a/gmime/gmime-message-part.c b/gmime/gmime-message-part.c
index 70022f6..d15d0db 100644
--- a/gmime/gmime-message-part.c
+++ b/gmime/gmime-message-part.c
@@ -216,7 +216,7 @@ g_mime_message_part_set_message (GMimeMessagePart *part, GMimeMessage *message)
  *
  * Gets the message object on the message part object @part.
  *
- * Returns: the message part contained within @part.
+ * Returns: (transfer none): the message part contained within @part.
  **/
 GMimeMessage *
 g_mime_message_part_get_message (GMimeMessagePart *part)
diff --git a/gmime/gmime-message-partial.c b/gmime/gmime-message-partial.c
index 8f2398c..3174c06 100644
--- a/gmime/gmime-message-partial.c
+++ b/gmime/gmime-message-partial.c
@@ -298,7 +298,8 @@ partial_compare (const void *v1, const void *v2)
  * Reconstructs the GMimeMessage from the given message/partial parts
  * in @partials.
  *
- * Returns: a GMimeMessage object on success or %NULL on fail.
+ * Returns: (transfer full): a GMimeMessage object on success or %NULL
+ * on fail.
  **/
 GMimeMessage *
 g_mime_message_partial_reconstruct_message (GMimeMessagePartial **partials, size_t num)
@@ -403,8 +404,8 @@ message_partial_message_new (GMimeMessage *base)
  * @max_size bytes or fewer. @nparts is set to the number of
  * #GMimeMessagePartial objects created.
  *
- * Returns: an array of #GMimeMessage objects and sets @nparts to th
- * number of messages returned or %NULL on fail.
+ * Returns: (transfer full): an array of #GMimeMessage objects and
+ * sets @nparts to the number of messages returned or %NULL on fail.
  **/
 GMimeMessage **
 g_mime_message_partial_split_message (GMimeMessage *message, size_t max_size, size_t *nparts)
diff --git a/gmime/gmime-message.c b/gmime/gmime-message.c
index b3426f2..15334fe 100644
--- a/gmime/gmime-message.c
+++ b/gmime/gmime-message.c
@@ -1223,8 +1223,8 @@ g_mime_message_add_recipient (GMimeMessage *message, GMimeRecipientType type, co
  *
  * Gets a list of recipients of type @type from @message.
  *
- * Returns: a list of recipients of a chosen type from the MIME
- * Message.
+ * Returns: (transfer none): a list of recipients of a chosen type
+ * from the MIME Message.
  **/
 InternetAddressList *
 g_mime_message_get_recipients (GMimeMessage *message, GMimeRecipientType type)
@@ -1242,8 +1242,9 @@ g_mime_message_get_recipients (GMimeMessage *message, GMimeRecipientType type)
  *
  * Gets the complete list of recipients for @message.
  *
- * Returns: a newly allocated #InternetAddressList containing all
- * recipients of the message or %NULL if no recipients are set.
+ * Returns: (transfer full): a newly allocated #InternetAddressList
+ * containing all recipients of the message or %NULL if no recipients
+ * are set.
  **/
 InternetAddressList *
 g_mime_message_get_all_recipients (GMimeMessage *message)
@@ -1343,8 +1344,8 @@ g_mime_message_set_date (GMimeMessage *message, time_t date, int tz_offset)
 /**
  * g_mime_message_get_date:
  * @message: MIME Message
- * @date: pointer to a date in time_t
- * @tz_offset: pointer to timezone offset (in +/- hours)
+ * @date: (out): pointer to a date in time_t
+ * @tz_offset: (out): pointer to timezone offset (in +/- hours)
  * 
  * Stores the date in time_t format in @date. If @tz_offset is
  * non-%NULL, then the timezone offset in will be stored in
@@ -1459,7 +1460,7 @@ g_mime_message_get_message_id (GMimeMessage *message)
  *
  * Gets the toplevel MIME part contained within @message.
  *
- * Returns: the toplevel MIME part of @message.
+ * Returns: (transfer none): the toplevel MIME part of @message.
  **/
 GMimeObject *
 g_mime_message_get_mime_part (GMimeMessage *message)
@@ -1515,7 +1516,8 @@ g_mime_message_set_mime_part (GMimeMessage *message, GMimeObject *mime_part)
 /**
  * g_mime_message_foreach:
  * @message: a #GMimeMessage
- * @callback: function to call on each of the mime parts contained by the mime message
+ * @callback: (scope call): function to call on each of the mime parts
+ *   contained by the mime message
  * @user_data: user-supplied callback data
  *
  * Recursively calls @callback on each of the mime parts in the mime message.
@@ -1592,8 +1594,8 @@ multipart_guess_body (GMimeMultipart *multipart)
  * Attempts to identify the MIME part containing the body of the
  * message.
  *
- * Returns: a #GMimeObject containing the textual content that appears
- * to be the main body of the message.
+ * Returns: (transfer none): a #GMimeObject containing the textual
+ * content that appears to be the main body of the message.
  *
  * Note: This function is NOT guarenteed to always work as it
  * makes some assumptions that are not necessarily true. It is
diff --git a/gmime/gmime-multipart-encrypted.c b/gmime/gmime-multipart-encrypted.c
index 8d602ad..f90fc13 100644
--- a/gmime/gmime-multipart-encrypted.c
+++ b/gmime/gmime-multipart-encrypted.c
@@ -145,7 +145,7 @@ g_mime_multipart_encrypted_new (void)
  * @sign: %TRUE if the content should also be signed or %FALSE otherwise
  * @userid: user id to use for signing (only used if @sign is %TRUE)
  * @digest: digest algorithm to use when signing
- * @recipients: an array of recipients to encrypt to
+ * @recipients: (element-type utf8): an array of recipients to encrypt to
  * @err: a #GError
  *
  * Attempts to encrypt (and conditionally sign) the @content MIME part
@@ -284,9 +284,9 @@ g_mime_data_wrapper_get_decoded_stream (GMimeDataWrapper *wrapper)
  * status information as well as a list of recipients that the part was
  * encrypted to.
  *
- * Returns: the decrypted MIME part on success or %NULL on fail. If the
- * decryption fails, an exception will be set on @err to provide
- * information as to why the failure occured.
+ * Returns: (transfer full): the decrypted MIME part on success or
+ * %NULL on fail. If the decryption fails, an exception will be set on
+ * @err to provide information as to why the failure occured.
  **/
 GMimeObject *
 g_mime_multipart_encrypted_decrypt (GMimeMultipartEncrypted *mpe, GMimeCryptoContext *ctx,
diff --git a/gmime/gmime-multipart-signed.c b/gmime/gmime-multipart-signed.c
index 16e5173..5a05390 100644
--- a/gmime/gmime-multipart-signed.c
+++ b/gmime/gmime-multipart-signed.c
@@ -365,9 +365,10 @@ check_protocol_supported (const char *protocol, const char *supported)
  * Attempts to verify the signed MIME part contained within the
  * multipart/signed object @mps using the @ctx crypto context.
  *
- * Returns: a new #GMimeSignatureList object on success or %NULL on fail. If
- * the verification fails, an exception will be set on @err to provide
- * information as to why the failure occured.
+ * Returns: (transfer full): a new #GMimeSignatureList object on
+ * success or %NULL on fail. If the verification fails, an exception
+ * will be set on @err to provide information as to why the failure
+ * occured.
  **/
 GMimeSignatureList *
 g_mime_multipart_signed_verify (GMimeMultipartSigned *mps, GMimeCryptoContext *ctx,
diff --git a/gmime/gmime-multipart.c b/gmime/gmime-multipart.c
index 977e2ab..b20ffb5 100644
--- a/gmime/gmime-multipart.c
+++ b/gmime/gmime-multipart.c
@@ -514,8 +514,8 @@ multipart_remove_at (GMimeMultipart *multipart, int index)
  *
  * Removes the mime part at position @index from the multipart.
  *
- * Returns: the mime part that was removed or %NULL if the part was
- * not contained within the multipart.
+ * Returns: (transfer full): the mime part that was removed or %NULL
+ * if the part was not contained within the multipart.
  **/
 GMimeObject *
 g_mime_multipart_remove_at (GMimeMultipart *multipart, int index)
@@ -536,8 +536,8 @@ g_mime_multipart_remove_at (GMimeMultipart *multipart, int index)
  * Replaces the mime part at position @index within @multipart with
  * @replacement.
  *
- * Returns: the mime part that was replaced or %NULL if the part was
- * not contained within the multipart.
+ * Returns: (transfer full): the mime part that was replaced or %NULL
+ * if the part was not contained within the multipart.
  **/
 GMimeObject *
 g_mime_multipart_replace (GMimeMultipart *multipart, int index, GMimeObject *replacement)
@@ -580,7 +580,7 @@ multipart_get_part (GMimeMultipart *multipart, int index)
  *
  * Gets the mime part at position @index within the multipart.
  *
- * Returns: the mime part at position @index.
+ * Returns: (transfer none): the mime part at position @index.
  **/
 GMimeObject *
 g_mime_multipart_get_part (GMimeMultipart *multipart, int index)
@@ -813,7 +813,8 @@ multipart_foreach (GMimeMultipart *multipart, GMimeObjectForeachFunc callback, g
 /**
  * g_mime_multipart_foreach: 
  * @multipart: a #GMimeMultipart
- * @callback: function to call for each of @multipart's subparts.
+ * @callback: (scope call): function to call for each of @multipart's
+ *   subparts.
  * @user_data: user-supplied callback data
  * 
  * Recursively calls @callback on each of @multipart's subparts.
@@ -836,8 +837,8 @@ g_mime_multipart_foreach (GMimeMultipart *multipart, GMimeObjectForeachFunc call
  * Gets the mime part with the content-id @content_id from the
  * multipart @multipart.
  *
- * Returns: the #GMimeObject whose content-id matches the search string,
- * or %NULL if a match cannot be found.
+ * Returns: (transfer none): the #GMimeObject whose content-id matches
+ * the search string, or %NULL if a match cannot be found.
  **/
 GMimeObject *
 g_mime_multipart_get_subpart_from_content_id (GMimeMultipart *multipart, const char *content_id)
diff --git a/gmime/gmime-object.c b/gmime/gmime-object.c
index 16477aa..08e636f 100644
--- a/gmime/gmime-object.c
+++ b/gmime/gmime-object.c
@@ -454,7 +454,8 @@ g_mime_object_set_content_type (GMimeObject *object, GMimeContentType *content_t
  * Gets the #GMimeContentType object for the given MIME object or
  * %NULL on fail.
  *
- * Returns: the content-type object for the specified MIME object.
+ * Returns: (transfer none): the content-type object for the specified
+ * MIME object.
  **/
 GMimeContentType *
 g_mime_object_get_content_type (GMimeObject *object)
@@ -510,7 +511,8 @@ g_mime_object_get_content_type_parameter (GMimeObject *object, const char *name)
  *
  * Gets the #GMimeContentDisposition for the specified MIME object.
  *
- * Returns: the #GMimeContentDisposition set on the MIME object.
+ * Returns: (transfer none): the #GMimeContentDisposition set on the
+ * MIME object.
  **/
 GMimeContentDisposition *
 g_mime_object_get_content_disposition (GMimeObject *object)
@@ -1035,8 +1037,8 @@ g_mime_object_to_string (GMimeObject *object)
  *
  * Get the header list for @object.
  *
- * Returns: the #GMimeHeaderList for @object. Do not free this pointer
- * when you are done with it.
+ * Returns: (transfer none): the #GMimeHeaderList for @object. Do not
+ * free this pointer when you are done with it.
  **/
 GMimeHeaderList *
 g_mime_object_get_header_list (GMimeObject *object)
diff --git a/gmime/gmime-param.c b/gmime/gmime-param.c
index 1686fc9..4dd98d5 100644
--- a/gmime/gmime-param.c
+++ b/gmime/gmime-param.c
@@ -46,7 +46,6 @@
 
 #define d(x)
 
-
 /**
  * SECTION: gmime-param
  * @title: GMimeParam
diff --git a/gmime/gmime-param.h b/gmime/gmime-param.h
index f4e4bab..2e7df18 100644
--- a/gmime/gmime-param.h
+++ b/gmime/gmime-param.h
@@ -43,7 +43,6 @@ struct _GMimeParam {
        char *value;
 };
 
-
 GMimeParam *g_mime_param_new (const char *name, const char *value);
 GMimeParam *g_mime_param_new_from_string (const char *str);
 void g_mime_param_destroy (GMimeParam *param);
diff --git a/gmime/gmime-parser.c b/gmime/gmime-parser.c
index b3d9347..4e26c7e 100644
--- a/gmime/gmime-parser.c
+++ b/gmime/gmime-parser.c
@@ -1893,7 +1893,8 @@ parser_construct_part (GMimeParser *parser)
  *
  * Constructs a MIME part from @parser.
  *
- * Returns: a MIME part based on @parser or %NULL on fail.
+ * Returns: (transfer full): a MIME part based on @parser or %NULL on
+ * fail.
  **/
 GMimeObject *
 g_mime_parser_construct_part (GMimeParser *parser)
@@ -1977,7 +1978,7 @@ parser_construct_message (GMimeParser *parser)
  *
  * Constructs a MIME message from @parser.
  *
- * Returns: a MIME message or %NULL on fail.
+ * Returns: (transfer full): a MIME message or %NULL on fail.
  **/
 GMimeMessage *
 g_mime_parser_construct_message (GMimeParser *parser)
diff --git a/gmime/gmime-part-iter.c b/gmime/gmime-part-iter.c
index 2019a2a..4edc7da 100644
--- a/gmime/gmime-part-iter.c
+++ b/gmime/gmime-part-iter.c
@@ -408,7 +408,7 @@ g_mime_part_iter_prev (GMimePartIter *iter)
  *
  * Gets the toplevel #GMimeObject used to initialize @iter.
  *
- * Returns: the toplevel #GMimeObject.
+ * Returns: (transfer none): the toplevel #GMimeObject.
  **/
 GMimeObject *
 g_mime_part_iter_get_toplevel (GMimePartIter *iter)
@@ -425,8 +425,8 @@ g_mime_part_iter_get_toplevel (GMimePartIter *iter)
  *
  * Gets the #GMimeObject at the current #GMimePartIter position.
  *
- * Returns: the current #GMimeObject or %NULL if the state of @iter is
- * invalid.
+ * Returns: (transfer none): the current #GMimeObject or %NULL if the
+ * state of @iter is invalid.
  **/
 GMimeObject *
 g_mime_part_iter_get_current (GMimePartIter *iter)
@@ -444,8 +444,8 @@ g_mime_part_iter_get_current (GMimePartIter *iter)
  * Gets the parent of the #GMimeObject at the current #GMimePartIter
  * position.
  *
- * Returns: the parent #GMimeObject or %NULL if the state of @iter is
- * invalid.
+ * Returns: (transfer none): the parent #GMimeObject or %NULL if the
+ * state of @iter is invalid.
  **/
 GMimeObject *
 g_mime_part_iter_get_parent (GMimePartIter *iter)
diff --git a/gmime/gmime-part.c b/gmime/gmime-part.c
index 1a43c70..ee358a2 100644
--- a/gmime/gmime-part.c
+++ b/gmime/gmime-part.c
@@ -887,7 +887,8 @@ g_mime_part_set_content_object (GMimePart *mime_part, GMimeDataWrapper *content)
  * Gets the internal data-wrapper of the specified mime part, or %NULL
  * on error.
  *
- * Returns: the data-wrapper for the mime part's contents.
+ * Returns: (transfer none): the data-wrapper for the mime part's
+ * contents.
  **/
 GMimeDataWrapper *
 g_mime_part_get_content_object (GMimePart *mime_part)
diff --git a/gmime/gmime-pkcs7-context.c b/gmime/gmime-pkcs7-context.c
index 5cdd079..abef395 100644
--- a/gmime/gmime-pkcs7-context.c
+++ b/gmime/gmime-pkcs7-context.c
@@ -890,7 +890,7 @@ pkcs7_export_keys (GMimeCryptoContext *context, GPtrArray *keys, GMimeStream *os
  *
  * Creates a new pkcs7 crypto context object.
  *
- * Returns: a new pkcs7 crypto context object.
+ * Returns: (transfer full): a new pkcs7 crypto context object.
  **/
 GMimeCryptoContext *
 g_mime_pkcs7_context_new (GMimePasswordRequestFunc request_passwd)
diff --git a/gmime/gmime-signature.c b/gmime/gmime-signature.c
index 6ec7068..11d8d88 100644
--- a/gmime/gmime-signature.c
+++ b/gmime/gmime-signature.c
@@ -216,7 +216,7 @@ g_mime_signature_set_certificate (GMimeSignature *sig, GMimeCertificate *cert)
  *
  * Get the signature's certificate.
  *
- * Returns: the signature's certificate.
+ * Returns: (transfer none): the signature's certificate.
  **/
 GMimeCertificate *
 g_mime_signature_get_certificate (GMimeSignature *sig)
@@ -586,8 +586,8 @@ g_mime_signature_list_index_of (GMimeSignatureList *list, GMimeSignature *sig)
  *
  * Gets the #GMimeSignature at the specified index.
  *
- * Returns: the #GMimeSignature at the specified index or %NULL if
- * the index is out of range.
+ * Returns: (transfer none): the #GMimeSignature at the specified
+ * index or %NULL if the index is out of range.
  **/
 GMimeSignature *
 g_mime_signature_list_get_signature (GMimeSignatureList *list, int index)
diff --git a/gmime/gmime-stream-gio.c b/gmime/gmime-stream-gio.c
index 5694147..b214ce0 100644
--- a/gmime/gmime-stream-gio.c
+++ b/gmime/gmime-stream-gio.c
@@ -636,7 +636,7 @@ stream_substream (GMimeStream *stream, gint64 start, gint64 end)
  *
  * Creates a new #GMimeStreamGIO wrapper around a #GFile object.
  *
- * Returns: a stream using @file.
+ * Returns: (transfer full): a stream using @file.
  **/
 GMimeStream *
 g_mime_stream_gio_new (GFile *file)
@@ -664,7 +664,8 @@ g_mime_stream_gio_new (GFile *file)
  * Creates a new #GMimeStreamGIO stream around a #GFile with bounds
  * @start and @end.
  *
- * Returns: a stream using @file with bounds @start and @end.
+ * Returns: (transfer full): a stream using @file with bounds @start
+ * and @end.
  **/
 GMimeStream *
 g_mime_stream_gio_new_with_bounds (GFile *file, gint64 start, gint64 end)
diff --git a/gmime/gmime-stream-mem.c b/gmime/gmime-stream-mem.c
index 7f38b9e..eaafeaa 100644
--- a/gmime/gmime-stream-mem.c
+++ b/gmime/gmime-stream-mem.c
@@ -373,7 +373,7 @@ g_mime_stream_mem_new_with_byte_array (GByteArray *array)
 
 /**
  * g_mime_stream_mem_new_with_buffer:
- * @buffer: stream data
+ * @buffer: (array length=len) (element-type guint8): stream data
  * @len: buffer length
  *
  * Creates a new #GMimeStreamMem object and initializes the stream
@@ -403,7 +403,7 @@ g_mime_stream_mem_new_with_buffer (const char *buffer, size_t len)
  *
  * Gets the byte array from the memory stream.
  *
- * Returns: the byte array from the memory stream.
+ * Returns: (transfer none): the byte array from the memory stream.
  **/
 GByteArray *
 g_mime_stream_mem_get_byte_array (GMimeStreamMem *mem)
diff --git a/gmime/gmime-stream.c b/gmime/gmime-stream.c
index a637bd3..f4c50aa 100644
--- a/gmime/gmime-stream.c
+++ b/gmime/gmime-stream.c
@@ -159,7 +159,7 @@ stream_read (GMimeStream *stream, char *buf, size_t len)
 /**
  * g_mime_stream_read:
  * @stream: a #GMimeStream
- * @buf: buffer
+ * @buf: (array length=len) (element-type guint8): buffer
  * @len: buffer length
  *
  * Attempts to read up to @len bytes from @stream into @buf.
@@ -433,7 +433,8 @@ stream_substream (GMimeStream *stream, gint64 start, gint64 end)
  *
  * Creates a new substream of @stream with bounds @start and @end.
  *
- * Returns: a substream of @stream with bounds @start and @end.
+ * Returns: (transfer full): a substream of @stream with bounds @start
+ * and @end.
  **/
 GMimeStream *
 g_mime_stream_substream (GMimeStream *stream, gint64 start, gint64 end)
diff --git a/gmime/gmime-utils.c b/gmime/gmime-utils.c
index 6dd4ee8..dc3f3b5 100644
--- a/gmime/gmime-utils.c
+++ b/gmime/gmime-utils.c
@@ -743,7 +743,7 @@ gmime_datetok_table_init (void)
 /**
  * g_mime_utils_header_decode_date:
  * @str: input date string
- * @tz_offset: timezone offset
+ * @tz_offset: (out): timezone offset
  *
  * Decodes the rfc822 date string and saves the GMT offset into
  * @tz_offset if non-NULL.
@@ -1399,7 +1399,8 @@ charset_convert (iconv_t cd, const char *inbuf, size_t inleft, char **outp, size
 
 /**
  * g_mime_utils_decode_8bit:
- * @text: input text in unknown 8bit/multibyte character set
+ * @text: (array length=len) (element-type guint8): input text in
+ *   unknown 8bit/multibyte character set
  * @len: input text length
  *
  * Attempts to convert text in an unknown 8bit/multibyte charset into
diff --git a/gmime/internet-address.c b/gmime/internet-address.c
index 45e2ed3..9a29d8a 100644
--- a/gmime/internet-address.c
+++ b/gmime/internet-address.c
@@ -496,7 +496,8 @@ internet_address_group_set_members (InternetAddressGroup *group, InternetAddress
  * Gets the #InternetAddressList containing the group members of an
  * rfc822 group address.
  *
- * Returns: a #InternetAddressList containing the members of @group.
+ * Returns: (transfer none): a #InternetAddressList containing the
+ * members of @group.
  **/
 InternetAddressList *
 internet_address_group_get_members (InternetAddressGroup *group)
@@ -926,8 +927,8 @@ internet_address_list_index_of (InternetAddressList *list, InternetAddress *ia)
  *
  * Gets the #InternetAddress at the specified index.
  *
- * Returns: the #InternetAddress at the specified index or %NULL if
- * the index is out of range.
+ * Returns: (transfer none): the #InternetAddress at the specified
+ * index or %NULL if the index is out of range.
  **/
 InternetAddress *
 internet_address_list_get_address (InternetAddressList *list, int index)
@@ -1546,8 +1547,8 @@ decode_address (const char **in)
  *
  * Construct a list of internet addresses from the given string.
  *
- * Returns: a #InternetAddressList or %NULL if the input string does
- * not contain any addresses.
+ * Returns: (transfer full): a #InternetAddressList or %NULL if the
+ * input string does not contain any addresses.
  **/
 InternetAddressList *
 internet_address_list_parse_string (const char *str)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]