[gtk+/wip/baedert/gtkimageview] First batch of documentation

[Timm Bäder <baedert src gnome org>]

commit ad748f0aa4f27442dd77a4fa1b781973f44c710e
Author: Timm Bäder <mail baedert org>
Date:   Mon Feb 8 19:48:49 2016 +0100

    First batch of documentation

 gtk/gtkimageview.c |  107 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 92 insertions(+), 15 deletions(-)
---
diff --git a/gtk/gtkimageview.c b/gtk/gtkimageview.c
index 33f8621..a432292 100644
--- a/gtk/gtkimageview.c
+++ b/gtk/gtkimageview.c
@@ -29,6 +29,9 @@
  *
  *   - Angle transition from 395 to 5 does a -390deg rotation
  *   - transition from !fit-allocation to fit-allocation and back
+ *   - We have lots of load functions taking a scale_factor param,
+ *     can we just explain that once and link to the section from there?
+ *   - Setting fit-allocation to FALSE sets the scale to 1.0. Is that right?
  *
  */
 
@@ -138,7 +141,6 @@ struct _LoadTaskData
 };
 
 
-/* Prototypes {{{ */
 static void gtk_image_view_update_surface (GtkImageView    *image_view,
                                            const GdkPixbuf *frame,
                                            int              scale_factor);
@@ -160,8 +162,6 @@ static void gtk_image_view_fix_anchor (GtkImageView *image_view,
                                        double        anchor_y,
                                        State        *old_state);
 
-/* }}} */
-
 
 static inline double
 gtk_image_view_get_real_scale (GtkImageView *image_view)
@@ -1215,11 +1215,17 @@ gtk_image_view_set_vscroll_policy (GtkImageView        *image_view,
  * @scale: The new scale value
  *
  * Sets the value of the #scale property. This will cause the
- * #scale-set property to be set to #TRUE as well
+ * #scale-set property to be set to #FALSE as well
  *
  * If #fit-allocation is #TRUE, it will be set to #FALSE, and @image_view
  * will be resized to the image's current size, taking the new scale into
  * account.
+ *
+ * If #transitions-enabled is set to #TRUE, the internal scale value will be
+ * interpolated between the old and the new scale, #gtk_image_view_get_scale
+ * will report the one passed to #gtk_image_view_set_scale however.
+ *
+ * Since: 3.20
  */
 void
 gtk_image_view_set_scale (GtkImageView *image_view,
@@ -1277,6 +1283,14 @@ gtk_image_view_set_scale (GtkImageView *image_view,
   gtk_widget_queue_resize (GTK_WIDGET (image_view));
 }
 
+/**
+ * gtk_image_view_set_scale:
+ * @image_view: A #GtkImageView instance
+ *
+ * Returns: The current scale applied to the image.
+ *
+ * Since: 3.20
+ */
 double
 gtk_image_view_get_scale (GtkImageView *image_view)
 {
@@ -1288,12 +1302,14 @@ gtk_image_view_get_scale (GtkImageView *image_view)
 
 /**
  * gtk_image_view_set_angle:
- * @image_view: A #GtkImageView
+ * @image_view: A #GtkImageView instance
  * @angle: The angle to rotate the image about, in
  *   degrees. If this is < 0 or > 360, the value will
  *   be wrapped. So e.g. setting this to 362 will result in a
  *   angle of 2, setting it to -2 will result in 358.
  *   Both 0 and 360 are possible.
+ *
+ * Since: 3.20
  */
 void
 gtk_image_view_set_angle (GtkImageView *image_view,
@@ -1346,6 +1362,14 @@ gtk_image_view_set_angle (GtkImageView *image_view,
     gtk_widget_queue_resize (GTK_WIDGET (image_view));
 }
 
+/**
+ * gtk_image_view_get_angle:
+ * @image_view: A #GtkImageView instance
+ *
+ * Returns: The current angle value.
+ *
+ * Since: 3.20
+ */
 double
 gtk_image_view_get_angle (GtkImageView *image_view)
 {
@@ -1355,8 +1379,6 @@ gtk_image_view_get_angle (GtkImageView *image_view)
   return priv->angle;
 }
 
-
-
 /**
  * gtk_image_view_set_snap_angle:
  * @image_view: A #GtkImageView instance
@@ -1365,7 +1387,9 @@ gtk_image_view_get_angle (GtkImageView *image_view)
  * Setting #snap-angle to #TRUE will cause @image_view's  angle to
  * be snapped to 90° steps. Setting the #angle property will cause it to
  * be set to the closest 90° step, so e.g. using an angle of 40 will result
- * in an angle of 0, using using 240 will result in 270, etc.
+ * in an angle of 0, using 240 will result in 270, etc.
+ *
+ * Since: 3.20
  */
 void
 gtk_image_view_set_snap_angle (GtkImageView *image_view,
@@ -1392,6 +1416,14 @@ gtk_image_view_set_snap_angle (GtkImageView *image_view,
     }
 }
 
+/**
+ * gtk_image_view_get_snap_angle:
+ * @image_view: A #GtkImageView instance
+ *
+ * Returns: The current value of the #snap-angle property.
+ *
+ * Since: 3.20
+ */
 gboolean
 gtk_image_view_get_snap_angle (GtkImageView *image_view)
 {
@@ -1417,6 +1449,8 @@ gtk_image_view_get_snap_angle (GtkImageView *image_view)
  * over the image's scale. Additionally, if the new #fit-allocation
  * value is #FALSE, the scale will be reset to 1.0 and the #GtkImageView
  * will be resized to take at least the image's real size.
+ *
+ * Since: 3.20
  */
 void
 gtk_image_view_set_fit_allocation (GtkImageView *image_view,
@@ -1451,6 +1485,14 @@ gtk_image_view_set_fit_allocation (GtkImageView *image_view,
   gtk_widget_queue_resize (GTK_WIDGET (image_view));
 }
 
+/**
+ * gtk_image_view_get_fit_allocation:
+ * @image_view: A #GtkImageView instance
+ *
+ * Returns: The current value of the #fit-allocation property.
+ *
+ * Since: 3.20
+ */
 gboolean
 gtk_image_view_get_fit_allocation (GtkImageView *image_view)
 {
@@ -1460,8 +1502,6 @@ gtk_image_view_get_fit_allocation (GtkImageView *image_view)
   return priv->fit_allocation;
 }
 
-
-
 void
 gtk_image_view_set_rotatable (GtkImageView *image_view,
                               gboolean      rotatable)
@@ -2197,8 +2237,19 @@ gtk_image_view_load_from_input_stream (GTask        *task,
     g_task_return_error (task, error);
 }
 
-
-
+/**
+ * gtk_image_view_load_from_file_async:
+ * @image_view: A #GtkImageView instance
+ * @file: The file to read from
+ * @scale_factor: Scale factor of the image. Pass 0 to use the
+ *   scale factor of @image_view
+ * @cancellable: (nullable): A #GCancellable that can be used to
+ *   cancel the loading operation
+ * @callback: (scope async): Callback to call once the operation finished
+ * @user_data: (closure): Data to pass to @callback
+ *
+ * Asynchronously loads an image from the given file.
+ */
 void
 gtk_image_view_load_from_file_async (GtkImageView        *image_view,
                                      GFile               *file,
@@ -2223,6 +2274,15 @@ gtk_image_view_load_from_file_async (GtkImageView        *image_view,
 
   g_object_unref (task);
 }
+
+/**
+ * gtk_image_view_load_from_file_finish:
+ * @image_view: A #GtkImageView instance
+ * @result: A #GAsyncResult
+ * @error: (nullable): Location to store error information in case the operation fails
+ *
+ * Returns: %TRUE if the operation succeeded, %FALSE otherwise.
+ */
 gboolean
 gtk_image_view_load_from_file_finish   (GtkImageView  *image_view,
                                         GAsyncResult  *result,
@@ -2233,9 +2293,17 @@ gtk_image_view_load_from_file_finish   (GtkImageView  *image_view,
   return g_task_propagate_boolean (G_TASK (result), error);
 }
 
-
-
-
+/**
+ * gtk_image_view_load_from_stream_async:
+ * @image_view: A #GtkImageView instance
+ * @input_stream: (transfer full): Input stream to read from
+ * @scale_factor: The scale factor of the read image
+ * @cancellable: (nullable): The GCancellable used to cancel the operation
+ * @callback: (scope async): A #GAsyncReadyCallback invoked when the operation finishes
+ * @user_data: (closure): The data to pass to @callback
+ *
+ * Asynchronously loads an image from the given input stream.
+ */
 void
 gtk_image_view_load_from_stream_async (GtkImageView        *image_view,
                                        GInputStream        *input_stream,
@@ -2260,6 +2328,15 @@ gtk_image_view_load_from_stream_async (GtkImageView        *image_view,
 
   g_object_unref (task);
 }
+
+/**
+ * gtk_image_view_load_from_stream_finish:
+ * @image_view: A #GtkImageView instance
+ * @result: A #GAsyncResult
+ * @error: (nullable): Location to store error information on failure
+ *
+ * Returns: %TRUE if the operation finished successfully, %FALSE otherwise.
+ */
 gboolean
 gtk_image_view_load_from_stream_finish (GtkImageView  *image_view,
                                         GAsyncResult  *result,