[gtk/picture-docs2] Add docs about sizing pictures

[Benjamin Otte <otte src gnome org>]

commit 7452773a01f20a3fcaab001e6385c4b6aebf4fa3
Author: Benjamin Otte <otte benjamin googlemail com>
Date:   Fri Dec 4 00:58:28 2020 +0000

    Add docs about sizing pictures
    
    Suggested by Christopher Davis.

 gtk/gtkpicture.c | 12 ++++++++++++
 1 file changed, 12 insertions(+)
---
diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 78e5ba449a..8674a9f9e7 100644
--- a/gtk/gtkpicture.c
+++ b/gtk/gtkpicture.c
@@ -56,6 +56,18 @@
  * In this case, gtk_picture_new_for_resource() and gtk_picture_set_resource()
  * should be used.
  *
+ * # sizing the paintable
+ *
+ * You can influence how the paintable is displayed inside the #GtkPicture. 
+ * By turning off GtkPicture::keep-aspect-ratio you can allow paintable
+ * to get stretched. GtkPicture::can-shrink can be unset to make
+ * sure that paintables are never made smaller than their ideal size - but be
+ * careful if you do not know the size of the paintable in use (like when)
+ * displaying user-loaded images) this can cause the picture to grow larger
+ * than the screen. And GtkWidget::halign and GtkWidget::valign can be used
+ * to make sure the paintable doesn't fill all available space but is instead
+ * displayed at its original size.
+ *
  * # CSS nodes
  *
  * GtkPicture has a single CSS node with the name picture.