Merge branch 'matthiasc/for-master' into 'master'

docs: Add details

See merge request GNOME/gtk!3084

gtk/gtkimage.c

@@ -44,7 +44,7 @@
  * SECTION:gtkimage
  * @Short_description: A widget displaying an image
  * @Title: GtkImage
- * @SeeAlso: #GdkTexture
+ * @SeeAlso: #GdkTexture, #GtkPicture
  *
  * The #GtkImage widget displays an image. Various kinds of object
  * can be displayed as an image; most typically, you would load a
@@ -67,6 +67,10 @@
  * In this case, the #GtkImage:resource, gtk_image_new_from_resource() and
  * gtk_image_set_from_resource() should be used.
  *
+ * GtkImage displays its image as an icon, with a size that is determined
+ * by the application. See #GtkPicture if you want to show an image at is
+ * actual size.
+ *
  * # CSS nodes
  *
  * GtkImage has a single CSS node with the name image. The style classes

gtk/gtkpicture.c

@@ -56,6 +56,9 @@
  * In this case, gtk_picture_new_for_resource() and gtk_picture_set_resource()
  * should be used.
  *
+ * GtkPicture displays an image at its natural size. See #GtkImage if you want
+ * to display a fixed-size image, such as an icon.
+ *
  * # Sizing the paintable
  *
  * You can influence how the paintable is displayed inside the #GtkPicture.