[gtk/matthiasc/for-master] docs: Add details

[Matthias Clasen <matthiasc src gnome org>]

commit a5e929ce36adc385dfcfcf600e97fd9c11c38e12
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jan 16 14:45:20 2021 -0500

    docs: Add details
    
    Explain the difference between GtkPicture and GtkImage,
    and when you might want to use which.

 gtk/gtkimage.c   | 6 +++++-
 gtk/gtkpicture.c | 3 +++
 2 files changed, 8 insertions(+), 1 deletion(-)
---
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index 730660ff06..5c53a5ede1 100644
--- a/gtk/gtkimage.c
+++ b/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
diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 6f0eb83240..0668cad14b 100644
--- a/gtk/gtkpicture.c
+++ b/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.