A bunch of annotation fixes from Eog

8 files changed, 140 insertions, 16 deletions

diff --git a/src/eom-application.c b/src/eom-application.c
index ea23410..d1797df 100644
--- a/src/eom-application.c
+++ b/src/eom-application.c
@@ -167,7 +167,7 @@ eom_application_init (EomApplication *eom_application)
  * Returns a singleton instance of #EomApplication currently running.
  * If not running yet, it will create one.
  *
- * Returns: a running #EomApplication.
+ * Returns: (transfer none): a running #EomApplication.
  **/
 EomApplication *
 eom_application_get_instance (void)
@@ -286,7 +286,7 @@ eom_application_show_window (EomWindow *window, gpointer user_data)
 /**
  * eom_application_open_file_list:
  * @application: An #EomApplication.
- * @file_list: A list of #GFile<!-- -->s.
+ * @file_list: (element-type GFile): A list of #GFile<!-- -->s
  * @timestamp: The timestamp of the user interaction which triggered this call
  * (see gtk_window_present_with_time()).
  * @flags: A set of #EomStartupFlags influencing a new windows' state.
@@ -336,7 +336,7 @@ eom_application_open_file_list (EomApplication  *application,
 /**
  * eom_application_open_uri_list:
  * @application: An #EomApplication.
- * @uri_list: A list of URIs.
+ * @uri_list: (element-type utf8): A list of URIs.
  * @timestamp: The timestamp of the user interaction which triggered this call
  * (see gtk_window_present_with_time()).
  * @flags: A set of #EomStartupFlags influencing a new windows' state.
@@ -433,7 +433,7 @@ eom_application_shutdown (EomApplication *application)
  * your own references if you want to perform actions that may destroy
  * them.
  *
- * Returns: A new list of #EomWindow<!-- -->s.
+ * Returns: (element-type EomWindow) (transfer container): A new list of #EomWindow<!-- -->s.
  **/
 GList *
 eom_application_get_windows (EomApplication *application)
@@ -462,7 +462,7 @@ eom_application_get_windows (EomApplication *application)
  *
  * Retrieves the #EggToolbarsModel for the toolbar in #EomApplication.
  *
- * Returns: An #EggToolbarsModel.
+ * Returns: (transfer none): An #EggToolbarsModel.
  **/
 EggToolbarsModel *
 eom_application_get_toolbars_model (EomApplication *application)
diff --git a/src/eom-error-message-area.c b/src/eom-error-message-area.c
index 9ea49a3..14a5362 100644
--- a/src/eom-error-message-area.c
+++ b/src/eom-error-message-area.c
@@ -126,6 +126,15 @@ create_error_message_area (const gchar *primary_text,
 	return message_area;
 }
 
+/**
+ * eom_image_load_error_message_area_new:
+ * @caption:
+ * @error:
+ *
+ *
+ *
+ * Returns: (transfer full): a new #GtkInfoArea
+ **/
 GtkWidget *
 eom_image_load_error_message_area_new (const gchar  *caption,
 				       const GError *error)
@@ -159,6 +168,14 @@ eom_image_load_error_message_area_new (const gchar  *caption,
 	return message_area;
 }
 
+/**
+ * eom_no_images_error_message_area_new:
+ * @file:
+ *
+ *
+ *
+ * Returns: (transfer full): a new #GtkInfoBar
+ **/
 GtkWidget *
 eom_no_images_error_message_area_new (GFile *file)
 {
diff --git a/src/eom-image.c b/src/eom-image.c
index 523f37f..a3ba6bc 100644
--- a/src/eom-image.c
+++ b/src/eom-image.c
@@ -1307,6 +1307,14 @@ eom_image_set_thumbnail (EomImage *img, GdkPixbuf *thumbnail)
 	}
 }
 
+/**
+ * eom_image_get_pixbuf:
+ * @img: a #EomImage
+ *
+ * Gets the #GdkPixbuf of the image
+ *
+ * Returns: (transfer full): a #GdkPixbuf
+ **/
 GdkPixbuf *
 eom_image_get_pixbuf (EomImage *img)
 {
@@ -1335,6 +1343,14 @@ eom_image_get_profile (EomImage *img)
 }
 #endif
 
+/**
+ * eom_image_get_thumbnail:
+ * @img: a #EomImage
+ *
+ * Gets the thumbnail pixbuf for @img
+ *
+ * Returns: (transfer full): a #GdkPixbuf with a thumbnail
+ **/
 GdkPixbuf *
 eom_image_get_thumbnail (EomImage *img)
 {
@@ -2014,6 +2030,15 @@ eom_image_get_exif_info (EomImage *img)
 }
 #endif
 
+/**
+ * eom_image_get_xmp_info:
+ * @img: a #EomImage
+ *
+ * Gets the XMP info for @img or NULL if compiled without
+ * libexempi support.
+ *
+ * Returns: (transfer full): the xmp data
+ **/
 gpointer
 eom_image_get_xmp_info (EomImage *img)
 {
@@ -2034,6 +2059,14 @@ eom_image_get_xmp_info (EomImage *img)
 }
 
 
+/**
+ * eom_image_get_file:
+ * @img: a #EomImage
+ *
+ * Gets the #GFile associated with @img
+ *
+ * Returns: (transfer full): a #GFile
+ **/
 GFile *
 eom_image_get_file (EomImage *img)
 {
@@ -2155,6 +2188,13 @@ compare_quarks (gconstpointer a, gconstpointer b)
 	return quark - GPOINTER_TO_INT (b);
 }
 
+/**
+ * eom_image_get_supported_mime_types:
+ *
+ * Gets the list of supported mimetypes
+ *
+ * Returns: (transfer none)(element-type utf8): a #GList of supported mimetypes
+ **/
 GList *
 eom_image_get_supported_mime_types (void)
 {
diff --git a/src/eom-properties-dialog.c b/src/eom-properties-dialog.c
index a7e484b..0214fa8 100644
--- a/src/eom-properties-dialog.c
+++ b/src/eom-properties-dialog.c
@@ -777,6 +777,18 @@ eom_properties_dialog_init (EomPropertiesDialog *prop_dlg)
 #endif
 }
 
+/**
+ * eom_properties_dialog_new:
+ * @parent: the dialog's parent window
+ * @thumbview:
+ * @next_image_action:
+ * @previous_image_action:
+ *
+ *
+ *
+ * Returns: (transfer full) (type EomPropertiesDialog): a new #EomPropertiesDialog
+ **/
+
 GObject *
 eom_properties_dialog_new (GtkWindow    *parent,
 			   EomThumbView *thumbview,
diff --git a/src/eom-thumb-view.c b/src/eom-thumb-view.c
index aba4eba..b83c4ac 100644
--- a/src/eom-thumb-view.c
+++ b/src/eom-thumb-view.c
@@ -893,7 +893,7 @@ eom_thumb_view_get_n_selected (EomThumbView *thumbview)
  * Gets the #EomImage stored in @thumbview's #EomListStore at the position indicated
  * by @path.
  *
- * Returns: A #EomImage.
+ * Returns: (transfer full): A #EomImage.
  **/
 static EomImage *
 eom_thumb_view_get_image_from_path (EomThumbView *thumbview, GtkTreePath *path)
@@ -953,7 +953,7 @@ eom_thumb_view_get_first_selected_image (EomThumbView *thumbview)
  * Gets a list with the currently selected images. Note that a new reference is
  * hold for each image and the list must be freed with g_list_free().
  *
- * Returns: A newly allocated list of #EomImage's.
+ * Returns: (element-type EomImage) (transfer full): A newly allocated list of #EomImage's.
  **/
 GList *
 eom_thumb_view_get_selected_images (EomThumbView *thumbview)
diff --git a/src/eom-thumbnail.c b/src/eom-thumbnail.c
index b7c5dc1..67b7137 100644
--- a/src/eom-thumbnail.c
+++ b/src/eom-thumbnail.c
@@ -377,6 +377,14 @@ eom_thumbnail_stretch_frame_image (GdkPixbuf *frame_image,
         return result_pixbuf;
 }
 
+/**
+ * eom_thumbnail_add_frame:
+ * @thumbnail: a #GdkPixbuf
+ *
+ * Adds a frame to @thumbnail
+ *
+ * Returns: (transfer full): a new #GdkPixbuf, storing @thumbnail nicely framed.
+ **/
 GdkPixbuf *
 eom_thumbnail_add_frame (GdkPixbuf *thumbnail)
 {
@@ -406,6 +414,15 @@ eom_thumbnail_add_frame (GdkPixbuf *thumbnail)
 	return result_pixbuf;
 }
 
+/**
+ * eom_thumbnail_fit_to_size:
+ * @thumbnail: a #GdkPixbuf
+ * @dimension: the maximum width or height desired
+ *
+ * Ensures a pixbuf fits a given @dimension
+ *
+ * Returns: (transfer full): a new #GdkPixbuf
+ **/
 GdkPixbuf *
 eom_thumbnail_fit_to_size (GdkPixbuf *thumbnail, gint dimension)
 {
@@ -434,6 +451,17 @@ eom_thumbnail_fit_to_size (GdkPixbuf *thumbnail, gint dimension)
 	return gdk_pixbuf_copy (thumbnail);
 }
 
+/**
+ * eom_thumbnail_load:
+ * @image: a #EomImage
+ * @error: location to store the error ocurring or %NULL to ignore
+ *
+ * Loads the thumbnail for @image. In case of error, %NULL is returned
+ * and @error is set.
+ *
+ * Returns: (transfer full): a new #GdkPixbuf with the thumbnail for
+ * @image or %NULL in case of error.
+ **/
 GdkPixbuf*
 eom_thumbnail_load (EomImage *image, GError **error)
 {
diff --git a/src/eom-transform.c b/src/eom-transform.c
index 8651915..5009fab 100644
--- a/src/eom-transform.c
+++ b/src/eom-transform.c
@@ -64,6 +64,16 @@ eom_transform_class_init (EomTransformClass *klass)
 	g_type_class_add_private (klass, sizeof (EomTransformPrivate));
 }
 
+/**
+ * eom_transform_apply:
+ * @trans: a #EomTransform
+ * @pixbuf: a #GdkPixbuf
+ * @job: a #EomJob
+ *
+ * Applies the transformation in @trans to @pixbuf, setting its progress in @job.
+ *
+ * Returns: (transfer full): A new #GdkPixbuf with the transformation applied.
+ **/
 GdkPixbuf*
 eom_transform_apply (EomTransform *trans, GdkPixbuf *pixbuf, EomJob *job)
 {
@@ -220,6 +230,14 @@ _eom_cairo_matrix_flip (cairo_matrix_t *dst, const cairo_matrix_t *src, gboolean
 	dst->y0 = vert ? -src->y0 : src->y0;
 }
 
+/**
+ * eom_transform_reverse:
+ * @trans: a #EomTransform
+ *
+ * Creates the reverse transformation of @trans
+ *
+ * Returns: (transfer full): a new transformation
+ **/
 EomTransform*
 eom_transform_reverse (EomTransform *trans)
 {
@@ -236,6 +254,15 @@ eom_transform_reverse (EomTransform *trans)
 	return reverse;
 }
 
+/**
+ * eom_transform_compose:
+ * @trans: a #EomTransform
+ * @compose: another #EomTransform
+ *
+ *
+ *
+ * Returns: (transfer full): a new transform
+ **/
 EomTransform*
 eom_transform_compose (EomTransform *trans, EomTransform *compose)
 {
diff --git a/src/eom-window.c b/src/eom-window.c
index 985368e..4645c83 100644
--- a/src/eom-window.c
+++ b/src/eom-window.c
@@ -5256,7 +5256,7 @@ eom_job_model_cb (EomJobModel *job, gpointer data)
 /**
  * eom_window_open_file_list:
  * @window: An #EomWindow.
- * @file_list: A %NULL-terminated list of #GFile's.
+ * @file_list: (element-type GFile): A %NULL-terminated list of #GFile's.
  *
  * Opens a list of files, adding them to the collection in @window.
  * Files will be checked to be readable and later filtered according
@@ -5291,7 +5291,7 @@ eom_window_open_file_list (EomWindow *window, GSList *file_list)
  *
  * Gets the #GtkUIManager that describes the UI of @window.
  *
- * Returns: A #GtkUIManager.
+ * Returns: (transfer none): A #GtkUIManager.
  **/
 GtkUIManager *
 eom_window_get_ui_manager (EomWindow *window)
@@ -5356,7 +5356,7 @@ eom_window_set_mode (EomWindow *window, EomWindowMode mode)
  * Gets the #EomListStore that contains the images in the collection
  * of @window.
  *
- * Returns: an #EomListStore.
+ * Returns: (transfer none): an #EomListStore.
  **/
 EomListStore *
 eom_window_get_store (EomWindow *window)
@@ -5372,7 +5372,7 @@ eom_window_get_store (EomWindow *window)
  *
  * Gets the #EomScrollView in the window.
  *
- * Returns: the #EomScrollView.
+ * Returns: (transfer none): the #EomScrollView.
  **/
 GtkWidget *
 eom_window_get_view (EomWindow *window)
@@ -5388,7 +5388,7 @@ eom_window_get_view (EomWindow *window)
  *
  * Gets the sidebar widget of @window.
  *
- * Returns: the #EomSidebar.
+ * Returns: (transfer none): the #EomSidebar.
  **/
 GtkWidget *
 eom_window_get_sidebar (EomWindow *window)
@@ -5404,7 +5404,7 @@ eom_window_get_sidebar (EomWindow *window)
  *
  * Gets the thumbnails view in @window.
  *
- * Returns: an #EomThumbView.
+ * Returns: (transfer none): an #EomThumbView.
  **/
 GtkWidget *
 eom_window_get_thumb_view (EomWindow *window)
@@ -5420,7 +5420,7 @@ eom_window_get_thumb_view (EomWindow *window)
  *
  * Gets the thumbnails navigation pane in @window.
  *
- * Returns: an #EomThumbNav.
+ * Returns: (transfer none): an #EomThumbNav.
  **/
 GtkWidget *
 eom_window_get_thumb_nav (EomWindow *window)
@@ -5436,7 +5436,7 @@ eom_window_get_thumb_nav (EomWindow *window)
  *
  * Gets the statusbar in @window.
  *
- * Returns: a #EomStatusBar.
+ * Returns: (transfer none): a #EomStatusBar.
  **/
 GtkWidget *
 eom_window_get_statusbar (EomWindow *window)
@@ -5453,7 +5453,7 @@ eom_window_get_statusbar (EomWindow *window)
  * Gets the image currently displayed in @window or %NULL if
  * no image is being displayed.
  *
- * Returns: an #EomImage.
+ * Returns: (transfer none): an #EomImage.
  **/
 EomImage *
 eom_window_get_image (EomWindow *window)