[gimp/gimp-2-10] app: add a doc-comment to gimp_widget_load_icon().

[Jehan <jehanp src gnome org>]

commit 4d4ba34006da3ca2a0b37293c6d87397168f46ee
Author: Jehan <jehan girinstud io>
Date:   Sun Jun 24 17:11:24 2018 +0200

    app: add a doc-comment to gimp_widget_load_icon().
    
    Mostly to make sure that calling code takes NULL as a possible return
    value.

 app/widgets/gimpwidgets-utils.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
---
diff --git a/app/widgets/gimpwidgets-utils.c b/app/widgets/gimpwidgets-utils.c
index 91601f198e..6faec2872f 100644
--- a/app/widgets/gimpwidgets-utils.c
+++ b/app/widgets/gimpwidgets-utils.c
@@ -366,6 +366,26 @@ gimp_enum_radio_frame_add (GtkFrame  *frame,
   gimp_enum_radio_box_add (GTK_BOX (box), widget, enum_value, below);
 }
 
+/**
+ * gimp_widget_load_icon:
+ * @widget:                  parent widget (to determine icon theme and
+ *                           style)
+ * @icon_name:               icon name
+ * @size:                    requested pixel size
+ *
+ * Loads an icon into a pixbuf with size as close as possible to @size.
+ * If icon does not exist or fail to load, the function will fallback to
+ * "gimp-wilber-eek" instead to prevent NULL pixbuf.
+ * Nevertheless it is still possible for this function to return NULL,
+ * in the edge case where "gimp-wilber-eek" is also missing, its file
+ * corrupted or maybe other reasons. So calling code must take the NULL
+ * return possibility into account.
+ *
+ * Return value: a newly allocated #GdkPixbuf containing @icon_name at
+ * size @size or a fallback icon/size. NULL return is a possibility in
+ * if neither the requested icon nor fallback could be loaded
+ * successfully.
+ **/
 GdkPixbuf *
 gimp_widget_load_icon (GtkWidget   *widget,
                        const gchar *icon_name,