[gtk+/wip/baedert/gtkimageview: 203/215] docs: Add a general description

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

commit c8778201c3ebc705e7fc4677c54e7d16dcc51723
Author: Timm Bäder <mail baedert org>
Date:   Tue Feb 9 11:19:58 2016 +0100

    docs: Add a general description

 gtk/gtkimageview.c |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkimageview.c b/gtk/gtkimageview.c
index 3fa8116..b0d8de2 100644
--- a/gtk/gtkimageview.c
+++ b/gtk/gtkimageview.c
@@ -20,7 +20,24 @@
  * @Short_description: A widget for displaying content images to users.
  * @Title: GtkImageView
  *
+ * #GtkImageView is a widget intended to be used to display "content images"
+ * to users. What we refer to as "content images" in the documentation could
+ * be characterized as "images the user is deeply interested in". You should
+ * use #GtkImageView whenever you want to actually present an image instead
+ * of just using an icon.
  *
+ * Contrary to #GtkImage, #GtkImageView does not just display an image with
+ * a fixed size, but provides ways of rotating and scaling it, as well as
+ * built-in gestures (via #GtkGestureRotate and #GtkGestureZoom) to rotate
+ * and zoom the image.
+ *
+ *
+ * ## Scale factor handling
+ *
+ * All the functions intended to set the image of a #GtkImageView instance take a
+ * "scale_factor" parameter (except for gtk_image_view_set_surface(), in which case
+ * the scale factor of the surface is taken instead). This scale factor can be interpreted
+ * the same as the #GtkWidget:scale-factor property of #GtkWidget, but for the given image.
  *
  * Since: 3.20
  */