GNOME.org
 

[gmime: 1/6] doc and g-ir-scanner fixes

commit a52e79295ca852b22127981f7a05c85a15525026
Author: Jeffrey Stedfast <fejj gnome org>
Date:   Thu Mar 30 09:31:26 2017 -0400

    doc and g-ir-scanner fixes

 gmime/GMime-3.0.metadata             |    5 -----
 gmime/gmime-application-pkcs7-mime.c |   24 +++++++++++++++++-------
 gmime/gmime-content-type.c           |    4 ++--
 gmime/gmime-crypto-context.c         |    2 +-
 gmime/gmime-disposition.c            |    4 ++--
 gmime/gmime-format-options.c         |    2 +-
 gmime/gmime-header.c                 |    2 +-
 gmime/gmime-message.c                |   12 ++++++------
 gmime/gmime-multipart-encrypted.c    |    6 +++---
 gmime/gmime-multipart-signed.c       |    6 +++---
 gmime/gmime-object.c                 |    2 +-
 gmime/gmime-param.c                  |    6 +++---
 gmime/gmime-parser-options.c         |    4 ++--
 gmime/gmime-stream-file.c            |    4 ++--
 gmime/gmime-stream-fs.c              |    4 ++--
 15 files changed, 46 insertions(+), 41 deletions(-)
---
diff --git a/gmime/GMime-3.0.metadata b/gmime/GMime-3.0.metadata
index 991c25b..d4886df 100644
--- a/gmime/GMime-3.0.metadata
+++ b/gmime/GMime-3.0.metadata
@@ -4,8 +4,6 @@ References struct=false
 
 // G-I can't handle non-boxed types
 PartIter struct=false
-Param struct=false
-  .next#method name="get_next" nullable
 
 // G-I doesn't allow non-nullable return values (bug #660879)
 Message
@@ -15,9 +13,6 @@ Object
 Parser
   .construct_message nullable
 
-// G-I doesn't have a time_t type
-utils_header_decode_date type="time_t"
-
 // G-I doesn't support annotations on fields (bug #561619)
 Filter
   .backbuf type="uint8[]" array_length_field="backsize"
diff --git a/gmime/gmime-application-pkcs7-mime.c b/gmime/gmime-application-pkcs7-mime.c
index 276d725..464f092 100644
--- a/gmime/gmime-application-pkcs7-mime.c
+++ b/gmime/gmime-application-pkcs7-mime.c
@@ -218,12 +218,15 @@ g_mime_application_pkcs7_mime_decompress (GMimeApplicationPkcs7Mime *pkcs7_mime,
  * g_mime_application_pkcs7_mime_encrypt:
  * @entity: a #GMimeObject to encrypt
  * @flags: a #GMimeEncryptFlags
- * @recipients: the list of recipients to encrypt to
+ * @recipients: (element-type utf8): an array of recipients to encrypt to
  * @err: a #GError
  *
- * Encrypts @entity using S/MIME.
+ * Attempts to encrypt the @entity MIME part to the public keys of @recipients
+ * using S/MIME. If successful, a new application/pkcs7-mime object is returned.
  *
- * Returns: The encrypted @entity.
+ * Returns: (transfer full): a new #GMimeApplicationPkcs7Mime object on success or
+ * %NULL on fail. If encrypting fails, an exception will be set on @err to provide
+ * information as to why the failure occured.
  **/
 GMimeApplicationPkcs7Mime *
 g_mime_application_pkcs7_mime_encrypt (GMimeObject *entity, GMimeEncryptFlags flags, GPtrArray *recipients, 
GError **err)
@@ -389,9 +392,12 @@ g_mime_application_pkcs7_mime_decrypt (GMimeApplicationPkcs7Mime *pkcs7_mime,
  * @userid: the user id to sign with
  * @err: a #GError
  *
- * Signs the @entity using S/MIME.
+ * Attempts to sign the @entity MIME part with @userid's private key using
+ * S/MIME. If successful, a new application/pkcs7-mime object is returned.
  *
- * Returns: the signed @entity.
+ * Returns: (transfer full): a new #GMimeApplicationPkcs7Mime object on success or
+ * %NULL on fail. If signing fails, an exception will be set on @err to provide
+ * information as to why the failure occured.
  **/
 GMimeApplicationPkcs7Mime *
 g_mime_application_pkcs7_mime_sign (GMimeObject *entity, const char *userid, GError **err)
@@ -456,9 +462,13 @@ g_mime_application_pkcs7_mime_sign (GMimeObject *entity, const char *userid, GEr
  * @entity: the extracted entity
  * @err: a #GError
  *
- * Verifies the signed @pkcs7_mime part and extracts the original MIME entity.
+ * Attempts to verify the signed @pkcs7_mime part and extract the original
+ * MIME entity.
  *
- * Returns: the list of signers.
+ * 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_application_pkcs7_mime_verify (GMimeApplicationPkcs7Mime *pkcs7_mime, GMimeVerifyFlags flags, 
GMimeObject **entity, GError **err)
diff --git a/gmime/gmime-content-type.c b/gmime/gmime-content-type.c
index 5b3b617..07dc181 100644
--- a/gmime/gmime-content-type.c
+++ b/gmime/gmime-content-type.c
@@ -182,7 +182,7 @@ g_mime_content_type_new (const char *type, const char *subtype)
  *
  * Parses the input string into a #GMimeContentType object.
  *
- * Returns: a new #GMimeContentType object based on the input string.
+ * Returns: (transfer full): a new #GMimeContentType object.
  **/
 GMimeContentType *
 g_mime_content_type_parse (GMimeParserOptions *options, const char *str)
@@ -400,7 +400,7 @@ g_mime_content_type_get_media_subtype (GMimeContentType *content_type)
  *
  * Gets the Content-Type's parameter list.
  *
- * Returns: the Content-Type's parameter list.
+ * Returns: (transfer none): the Content-Type's parameter list.
  **/
 GMimeParamList *
 g_mime_content_type_get_parameters (GMimeContentType *content_type)
diff --git a/gmime/gmime-crypto-context.c b/gmime/gmime-crypto-context.c
index ee850eb..3cf969e 100644
--- a/gmime/gmime-crypto-context.c
+++ b/gmime/gmime-crypto-context.c
@@ -563,7 +563,7 @@ crypto_export_keys (GMimeCryptoContext *ctx, const char *keys[],
 /**
  * g_mime_crypto_context_export_keys:
  * @ctx: a #GMimeCryptoContext
- * @keys: (element-type utf8): an array of key ids, terminated by a %NULL element
+ * @keys: an array of key ids, terminated by a %NULL element
  * @ostream: output stream
  * @err: a #GError
  *
diff --git a/gmime/gmime-disposition.c b/gmime/gmime-disposition.c
index fb4026d..77070cb 100644
--- a/gmime/gmime-disposition.c
+++ b/gmime/gmime-disposition.c
@@ -143,7 +143,7 @@ g_mime_content_disposition_new (void)
  *
  * Parses the input string into a #GMimeContentDisposition object.
  *
- * Returns: a new #GMimeContentDisposition object.
+ * Returns: (transfer full): a new #GMimeContentDisposition object.
  **/
 GMimeContentDisposition *
 g_mime_content_disposition_parse (GMimeParserOptions *options, const char *str)
@@ -228,7 +228,7 @@ g_mime_content_disposition_get_disposition (GMimeContentDisposition *disposition
  *
  * Gets the Content-Disposition parameter list.
  *
- * Returns: the Content-Disposition's parameter list.
+ * Returns: (transfer none): the Content-Disposition's parameter list.
  **/
 GMimeParamList *
 g_mime_content_disposition_get_parameters (GMimeContentDisposition *disposition)
diff --git a/gmime/gmime-format-options.c b/gmime/gmime-format-options.c
index 500503d..18a2908 100644
--- a/gmime/gmime-format-options.c
+++ b/gmime/gmime-format-options.c
@@ -343,7 +343,7 @@ g_mime_format_options_set_allow_international (GMimeFormatOptions *options, gboo
 
 
 /**
- * g_mime_format_options_get_allow_international:
+ * g_mime_format_options_get_max_line:
  * @options: a #GMimeFormatOptions or %NULL
  *
  * Gets the max line length to use with encoders.
diff --git a/gmime/gmime-header.c b/gmime/gmime-header.c
index ef94c9d..ce1c16d 100644
--- a/gmime/gmime-header.c
+++ b/gmime/gmime-header.c
@@ -1243,7 +1243,7 @@ g_mime_header_list_append (GMimeHeaderList *headers, const char *name, const cha
  *
  * Gets the first header with the specified name.
  *
- * Returns: a #GMimeHeader for the specified @name.
+ * Returns: (transfer none): a #GMimeHeader for the specified @name.
  **/
 GMimeHeader *
 g_mime_header_list_get_header (GMimeHeaderList *headers, const char *name)
diff --git a/gmime/gmime-message.c b/gmime/gmime-message.c
index 0b4c7f5..1e035d7 100644
--- a/gmime/gmime-message.c
+++ b/gmime/gmime-message.c
@@ -637,7 +637,7 @@ g_mime_message_new (gboolean pretty_headers)
  *
  * Gets the parsed list of addresses in the Sender header.
  *
- * Returns: the parsed list of addresses in the Sender header.
+ * Returns: (transfer none): the parsed list of addresses in the Sender header.
  **/
 InternetAddressList *
 g_mime_message_get_sender (GMimeMessage *message)
@@ -654,7 +654,7 @@ g_mime_message_get_sender (GMimeMessage *message)
  *
  * Gets the parsed list of addresses in the From header.
  *
- * Returns: the parsed list of addresses in the From header.
+ * Returns: (transfer none): the parsed list of addresses in the From header.
  **/
 InternetAddressList *
 g_mime_message_get_from (GMimeMessage *message)
@@ -671,7 +671,7 @@ g_mime_message_get_from (GMimeMessage *message)
  *
  * Gets the parsed list of addresses in the Reply-To header.
  *
- * Returns: the parsed list of addresses in the Reply-To header.
+ * Returns: (transfer none): the parsed list of addresses in the Reply-To header.
  **/
 InternetAddressList *
 g_mime_message_get_reply_to (GMimeMessage *message)
@@ -688,7 +688,7 @@ g_mime_message_get_reply_to (GMimeMessage *message)
  *
  * Gets combined list of parsed addresses in the To header(s).
  *
- * Returns: the parsed list of addresses in the To header(s).
+ * Returns: (transfer none): the parsed list of addresses in the To header(s).
  **/
 InternetAddressList *
 g_mime_message_get_to (GMimeMessage *message)
@@ -705,7 +705,7 @@ g_mime_message_get_to (GMimeMessage *message)
  *
  * Gets combined list of parsed addresses in the Cc header(s).
  *
- * Returns: the parsed list of addresses in the Cc header(s).
+ * Returns: (transfer none): the parsed list of addresses in the Cc header(s).
  **/
 InternetAddressList *
 g_mime_message_get_cc (GMimeMessage *message)
@@ -722,7 +722,7 @@ g_mime_message_get_cc (GMimeMessage *message)
  *
  * Gets combined list of parsed addresses in the Bcc header(s).
  *
- * Returns: the parsed list of addresses in the Bcc header(s).
+ * Returns: (transfer none): the parsed list of addresses in the Bcc header(s).
  **/
 InternetAddressList *
 g_mime_message_get_bcc (GMimeMessage *message)
diff --git a/gmime/gmime-multipart-encrypted.c b/gmime/gmime-multipart-encrypted.c
index 084dd5c..eacd0a8 100644
--- a/gmime/gmime-multipart-encrypted.c
+++ b/gmime/gmime-multipart-encrypted.c
@@ -151,9 +151,9 @@ g_mime_multipart_encrypted_new (void)
  * to the public keys of @recipients using the @ctx encryption
  * context. If successful, a new multipart/encrypted object is returned.
  *
- * Returns: a new #GMimeMultipartEncrypted object on success or %NULL on fail.
- * If encrypting fails, an exception will be set on @err to provide information
- * as to why the failure occured.
+ * Returns: (transfer full): a new #GMimeMultipartEncrypted object on success or
+ * %NULL on fail. If encrypting fails, an exception will be set on @err to provide
+ * information as to why the failure occured.
  **/
 GMimeMultipartEncrypted *
 g_mime_multipart_encrypted_encrypt (GMimeCryptoContext *ctx, GMimeObject *entity, gboolean sign, const char 
*userid,
diff --git a/gmime/gmime-multipart-signed.c b/gmime/gmime-multipart-signed.c
index 196e33b..9438c2f 100644
--- a/gmime/gmime-multipart-signed.c
+++ b/gmime/gmime-multipart-signed.c
@@ -204,9 +204,9 @@ sign_prepare (GMimeObject *mime_part)
  * using the @ctx signing context. If successful, a new multipart/signed
  * object is returned.
  *
- * Returns: a new #GMimeMultipartSigned object on success or %NULL on fail.
- * If signing fails, an exception will be set on @err to provide information
- * as to why the failure occured.
+ * Returns: (transfer full): a new #GMimeMultipartSigned object on success or
+ * %NULL on fail. If signing fails, an exception will be set on @err to provide
+ * information as to why the failure occured.
  **/
 GMimeMultipartSigned *
 g_mime_multipart_signed_sign (GMimeCryptoContext *ctx, GMimeObject *entity,
diff --git a/gmime/gmime-object.c b/gmime/gmime-object.c
index f59042d..30cc469 100644
--- a/gmime/gmime-object.c
+++ b/gmime/gmime-object.c
@@ -628,7 +628,7 @@ g_mime_object_get_content_disposition (GMimeObject *object)
 }
 
 /**
- * g_mime_object_set_content_disposition:
+ * _g_mime_object_set_content_disposition:
  * @object: a #GMimeObject
  * @disposition: a #GMimeContentDisposition object
  *
diff --git a/gmime/gmime-param.c b/gmime/gmime-param.c
index 5d2908a..9ff02a5 100644
--- a/gmime/gmime-param.c
+++ b/gmime/gmime-param.c
@@ -502,7 +502,7 @@ g_mime_param_list_set_parameter (GMimeParamList *list, const char *name, const c
  *
  * Gets the #GMimeParam with the given @name.
  *
- * Returns: the requested #GMimeParam.
+ * Returns: (transfer none): the requested #GMimeParam.
  **/
 GMimeParam *
 g_mime_param_list_get_parameter (GMimeParamList *list, const char *name)
@@ -531,7 +531,7 @@ g_mime_param_list_get_parameter (GMimeParamList *list, const char *name)
  *
  * Gets the #GMimeParam at the specified @index.
  *
- * Returns: the #GMimeParam at the specified index.
+ * Returns: (transfer none): the #GMimeParam at the specified index.
  **/
 GMimeParam *
 g_mime_param_list_get_parameter_at (GMimeParamList *list, int index)
@@ -1427,7 +1427,7 @@ decode_param_list (GMimeParserOptions *options, const char *in)
  *
  * Parses the input string into a parameter list.
  *
- * Returns: a #GMimeParamList.
+ * Returns: (transfer full): a new #GMimeParamList.
  **/
 GMimeParamList *
 g_mime_param_list_parse (GMimeParserOptions *options, const char *str)
diff --git a/gmime/gmime-parser-options.c b/gmime/gmime-parser-options.c
index 8057bbf..73cc0cb 100644
--- a/gmime/gmime-parser-options.c
+++ b/gmime/gmime-parser-options.c
@@ -291,8 +291,8 @@ g_mime_parser_options_set_rfc2047_compliance_mode (GMimeParserOptions *options,
  *
  * Gets the fallback charsets to try when decoding 8-bit headers.
  *
- * Returns: a %NULL-terminated list of charsets to try when decoding
- * 8-bit headers.
+ * Returns: (transfer none): a %NULL-terminated list of charsets to try when
+ * decoding 8-bit headers.
  **/
 const char **
 g_mime_parser_options_get_fallback_charsets (GMimeParserOptions *options)
diff --git a/gmime/gmime-stream-file.c b/gmime/gmime-stream-file.c
index e38d8b1..e95f7f0 100644
--- a/gmime/gmime-stream-file.c
+++ b/gmime/gmime-stream-file.c
@@ -431,8 +431,8 @@ g_mime_stream_file_new_with_bounds (FILE *fp, gint64 start, gint64 end)
  *
  * Creates a new #GMimeStreamFile object for the specified @path.
  *
- * Returns: a stream using for reading and/or writing to the specified
- * file path or %NULL on error.
+ * Returns: (transfer full): a stream using for reading and/or writing to the
+ * specified file path or %NULL on error.
  **/
 GMimeStream *
 g_mime_stream_file_open (const char *path, const char *mode, GError **err)
diff --git a/gmime/gmime-stream-fs.c b/gmime/gmime-stream-fs.c
index 5d14b2b..66ab740 100644
--- a/gmime/gmime-stream-fs.c
+++ b/gmime/gmime-stream-fs.c
@@ -474,8 +474,8 @@ g_mime_stream_fs_new_with_bounds (int fd, gint64 start, gint64 end)
  *
  * Creates a new #GMimeStreamFs object for the specified @path.
  *
- * Returns: a stream using for reading and/or writing to the specified
- * file path or %NULL on error.
+ * Returns: (transfer full): a stream using for reading and/or writing to the
+ * specified file path or %NULL on error.
  **/
 GMimeStream *
 g_mime_stream_fs_open (const char *path, int flags, int mode, GError **err)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]