[evolution-data-server] Bug 667388 â Introspection annotation fixes for nullable return types

[Philip Withnall <pwithnall src gnome org>]

commit e28afe79702ef9ae924e2c9620a2574177a965ac
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Jan 5 22:27:02 2012 +0000

    Bug 667388 â Introspection annotation fixes for nullable return types
    
    Add some missing (allow-none) annotations, as well as some (transfer full)
    annotations, to libebook and libedataserver. Update the documentation to
    match, and to be a little more descriptive in places.
    
    Closes: https://bugzilla.gnome.org/show_bug.cgi?id=667388

 addressbook/libebook/e-contact.c |   10 +++++-----
 addressbook/libebook/e-vcard.c   |   30 ++++++++++++++++--------------
 libedataserver/e-source-list.c   |    2 +-
 vala/EBook-1.2.metadata          |    7 +++++++
 vala/EDataServer-1.2.metadata    |    1 +
 vala/Makefile.am                 |    7 ++++++-
 6 files changed, 36 insertions(+), 21 deletions(-)
---
diff --git a/addressbook/libebook/e-contact.c b/addressbook/libebook/e-contact.c
index edccdbe..22ac944 100644
--- a/addressbook/libebook/e-contact.c
+++ b/addressbook/libebook/e-contact.c
@@ -1478,7 +1478,7 @@ e_contact_field_id_from_vcard (const gchar *vcard_field)
  *
  * Gets the value of @contact's field specified by @field_id.
  *
- * Returns: (transfer full): Depends on the field's type, owned by the caller.
+ * Returns: (transfer full) (allow-none): Depends on the field's type, owned by the caller. This may be %NULL if the field isn't set.
  **/
 gpointer
 e_contact_get (EContact *contact,
@@ -2143,8 +2143,8 @@ e_contact_photo_copy (EContactPhoto *photo)
  *
  * Gets the @photo's data.
  *
- * Returns: (transfer none) (array length=len): the inlined image in the
- * #EContactPhoto.
+ * Returns: (transfer none) (array length=len) (allow-none): the inlined image in the
+ * #EContactPhoto, or %NULL if it has not been set.
  *
  * Since: 3.2
  **/
@@ -2188,7 +2188,7 @@ e_contact_photo_set_inlined (EContactPhoto *photo,
  *
  * Gets the @photo's mime type.
  *
- * Returns: (transfer none): the mime type of the image
+ * Returns: (transfer none) (allow-none): the MIME type of the image, or %NULL if it has not been set.
  *
  * Since: 3.2
  **/
@@ -2227,7 +2227,7 @@ e_contact_photo_set_mime_type (EContactPhoto *photo,
  *
  * Gets the @photo's URI.
  *
- * Returns: (transfer none): the URI of the image
+ * Returns: (transfer none) (allow-none): the URI of the image, or %NULL if it has not been set
  *
  * Since: 3.2
  **/
diff --git a/addressbook/libebook/e-vcard.c b/addressbook/libebook/e-vcard.c
index 41d40bb..aa915a6 100644
--- a/addressbook/libebook/e-vcard.c
+++ b/addressbook/libebook/e-vcard.c
@@ -1468,7 +1468,7 @@ e_vcard_remove_attribute (EVCard *evc,
 /**
  * e_vcard_append_attribute:
  * @evc: an #EVCard
- * @attr: an #EVCardAttribute to append
+ * @attr: (transfer full): an #EVCardAttribute to append
  *
  * Appends @attr to @evc to the end of a list of attributes.
  *
@@ -1493,7 +1493,7 @@ e_vcard_append_attribute (EVCard *evc,
 /**
  * e_vcard_append_attribute_with_value:
  * @evcard: an #EVCard
- * @attr: an #EVCardAttribute to append
+ * @attr: (transfer full): an #EVCardAttribute to append
  * @value: a value to assign to the attribute
  *
  * Appends @attr to @evcard, setting it to @value.
@@ -1517,7 +1517,7 @@ e_vcard_append_attribute_with_value (EVCard *evcard,
 /**
  * e_vcard_append_attribute_with_values:
  * @evcard: an @EVCard
- * @attr: an #EVCardAttribute to append
+ * @attr: (transfer full): an #EVCardAttribute to append
  * @Varargs: a %NULL-terminated list of values to assign to the attribute
  *
  * Appends @attr to @evcard, assigning the list of values to it.
@@ -1573,7 +1573,7 @@ e_vcard_add_attribute (EVCard *evc,
 /**
  * e_vcard_add_attribute_with_value:
  * @evcard: an #EVCard
- * @attr: an #EVCardAttribute to add
+ * @attr: (transfer full): an #EVCardAttribute to add
  * @value: a value to assign to the attribute
  *
  * Adds @attr to @evcard, setting it to @value. For attribute addition
@@ -1595,7 +1595,7 @@ e_vcard_add_attribute_with_value (EVCard *evcard,
 /**
  * e_vcard_add_attribute_with_values:
  * @evcard: an @EVCard
- * @attr: an #EVCardAttribute to add
+ * @attr: (transfer full): an #EVCardAttribute to add
  * @Varargs: a %NULL-terminated list of values to assign to the attribute
  *
  * Adds @attr to @evcard, assigning the list of values to it.
@@ -2029,7 +2029,7 @@ e_vcard_attribute_param_add_values (EVCardAttributeParam *param,
 /**
  * e_vcard_attribute_add_param_with_value:
  * @attr: an #EVCardAttribute
- * @param: an #EVCardAttributeParam
+ * @param: (transfer full): an #EVCardAttributeParam
  * @value: a string value
  *
  * Adds @value to @param, then adds @param to @attr.
@@ -2050,7 +2050,7 @@ e_vcard_attribute_add_param_with_value (EVCardAttribute *attr,
 /**
  * e_vcard_attribute_add_param_with_values:
  * @attr: an #EVCardAttribute
- * @param: an #EVCardAttributeParam
+ * @param: (transfer full): an #EVCardAttributeParam
  * @Varargs: a %NULL-terminated list of strings
  *
  * Adds the list of values to @param, then adds @param
@@ -2158,10 +2158,10 @@ e_vcard_get_attributes (EVCard *evcard)
  * @name: the name of the attribute to get
  *
  * Get the attribute @name from @evc.  The #EVCardAttribute is owned by
- * @evcard and should not be freed. If the attribute does not exist, #NULL is
+ * @evcard and should not be freed. If the attribute does not exist, %NULL is
  * returned.
  *
- * Returns: (transfer none): An #EVCardAttribute if found, or #NULL.
+ * Returns: (transfer none) (allow-none): An #EVCardAttribute if found, or %NULL.
  **/
 EVCardAttribute *
 e_vcard_get_attribute (EVCard *evc,
@@ -2200,7 +2200,7 @@ e_vcard_get_attribute (EVCard *evc,
  * Similar to e_vcard_get_attribute() but this method will not attempt to
  * parse the vcard if not already parsed.
  *
- * Returns: (transfer none): An #EVCardAttribute if found, or #NULL.
+ * Returns: (transfer none) (allow-none): An #EVCardAttribute if found, or %NULL.
  *
  * Since: 3.4
  **/
@@ -2229,7 +2229,7 @@ e_vcard_get_attribute_if_parsed (EVCard *evc,
  *
  * Gets the group name of @attr.
  *
- * Returns: The attribute's group name.
+ * Returns: (allow-none): The attribute's group name, or %NULL.
  **/
 const gchar *
 e_vcard_attribute_get_group (EVCardAttribute *attr)
@@ -2262,7 +2262,9 @@ e_vcard_attribute_get_name (EVCardAttribute *attr)
  * Gets the list of values from @attr. The list and its
  * contents are owned by @attr, and must not be freed.
  *
- * Returns: (transfer none) (element-type utf8): A list of string values.
+ * Returns: (transfer none) (element-type utf8): A list of string values. They
+ * will all be non-%NULL, but may be empty strings. The list itself may be
+ * empty.
  **/
 GList *
 e_vcard_attribute_get_values (EVCardAttribute *attr)
@@ -2341,7 +2343,7 @@ e_vcard_attribute_is_single_valued (EVCardAttribute *attr)
  *
  * Gets the value of a single-valued #EVCardAttribute, @attr.
  *
- * Returns: A newly allocated string representing the value.
+ * Returns: (allow-none): A newly allocated string representing the value, or %NULL if the attribute has no value.
  **/
 gchar *
 e_vcard_attribute_get_value (EVCardAttribute *attr)
@@ -2367,7 +2369,7 @@ e_vcard_attribute_get_value (EVCardAttribute *attr)
  *
  * Note: this function seems currently to be unused. Could be removed.
  *
- * Returns: A newly allocated #GString representing the value.
+ * Returns: (allow-none): A newly allocated #GString representing the value, or %NULL if the attribute has no value.
  **/
 GString *
 e_vcard_attribute_get_value_decoded (EVCardAttribute *attr)
diff --git a/libedataserver/e-source-list.c b/libedataserver/e-source-list.c
index 1b3849e..cea5c34 100644
--- a/libedataserver/e-source-list.c
+++ b/libedataserver/e-source-list.c
@@ -609,7 +609,7 @@ e_source_list_peek_source_any (ESourceList *list)
  * property named "system".  If no such #ESource exists, the function
  * returns %NULL.
  *
- * Returns: (transfer none): the default #ESource in @list, or %NULL
+ * Returns: (transfer none) (allow-none): the default #ESource in @list, or %NULL
  *
  * Since: 2.32
  **/
diff --git a/vala/EBook-1.2.metadata b/vala/EBook-1.2.metadata
index f91c00e..0a46e29 100644
--- a/vala/EBook-1.2.metadata
+++ b/vala/EBook-1.2.metadata
@@ -17,3 +17,10 @@ ContactAddress.locality unowned=false
 ContactAddress.po unowned=false
 ContactAddress.region unowned=false
 ContactAddress.street unowned=false
+ContactPhoto.get_inlined nullable=true
+ContactPhoto.get_mime_type nullable=true
+ContactPhoto.get_uri nullable=true
+VCard.get_attribute nullable=true
+VCard.get_attribute_if_parsed nullable=true
+VCardAttribute.get_group nullable=true
+VCardAttribute.get_value nullable=true
diff --git a/vala/EDataServer-1.2.metadata b/vala/EDataServer-1.2.metadata
new file mode 100644
index 0000000..95ed471
--- /dev/null
+++ b/vala/EDataServer-1.2.metadata
@@ -0,0 +1 @@
+SourceList.peek_default_source nullable=true
diff --git a/vala/Makefile.am b/vala/Makefile.am
index 6a202aa..3c35ede 100644
--- a/vala/Makefile.am
+++ b/vala/Makefile.am
@@ -9,7 +9,11 @@ dist_vapi_DATA = \
 	libecalendar-1.2.deps \
 	$(NULL)
 
-EXTRA_DIST = EBook-1.2.metadata ECalendar-1.2.metadata
+EXTRA_DIST = \
+	EBook-1.2.metadata \
+	ECalendar-1.2.metadata \
+	EDataServer-1.2.metadata \
+	$(NULL)
 
 BUILT_SOURCES = \
 	$(vapi_DATA) \
@@ -21,6 +25,7 @@ libedataserver-1.2.vapi: $(top_builddir)/libedataserver/EDataServer-1.2.gir
 	$(VAPIGEN_V)$(VAPIGEN) \
 		--pkg gio-2.0 \
 		--library libedataserver-1.2 \
+		--metadatadir=$(srcdir) \
 		$< \
 		$(NULL)
 	@mv $@ libedataserver-1.2.vapi.tmp