[gnome-software: 1/2] gs-appstream: Add code comments documenting intent for icons

[Milan Crha <mcrha src gnome org>]

commit 16ec6d7cfe9006c760eaa379c2c9cf574a72d263
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu Mar 10 18:56:00 2022 +0000

    gs-appstream: Add code comments documenting intent for icons
    
    Make it a bit clearer when the I/O for loading icons is expected to
    happen.
    
    See: https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/1286
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 lib/gs-appstream.c | 6 ++++++
 1 file changed, 6 insertions(+)
---
diff --git a/lib/gs-appstream.c b/lib/gs-appstream.c
index 14cf8887f..4188c8581 100644
--- a/lib/gs-appstream.c
+++ b/lib/gs-appstream.c
@@ -205,6 +205,7 @@ gs_appstream_build_icon_prefix (XbNode *component)
        return g_strjoinv ("/", path);
 }
 
+/* This function is designed to do no disk or network I/O. */
 static AsIcon *
 gs_appstream_new_icon (XbNode *component, XbNode *n, AsIconKind icon_kind, guint sz)
 {
@@ -259,6 +260,11 @@ gs_appstream_refine_icon (GsApp *app, XbNode *component)
        if (icons == NULL)
                return;
 
+       /* This code deliberately does *not* check that the icon files or theme
+        * icons exist, as that would mean doing disk I/O for all the apps in
+        * the appstream file, regardless of whether the calling code is
+        * actually going to use the icons. Better to add all the possible icons
+        * and let the calling code check which ones exist, if it needs to. */
        for (guint i = 0; i < icons->len; i++) {
                XbNode *icon_node = g_ptr_array_index (icons, i);
                g_autoptr(AsIcon) icon = NULL;