From ba7de5d33d4b8ae6a35f587ebd2ae022267a665a Mon Sep 17 00:00:00 2001
From: Jack251970 <1160210343@qq.com>
Date: Tue, 23 Sep 2025 21:39:42 +0800
Subject: [PATCH] Add documents

---
 .../Image/ThumbnailReader.cs                  | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/Flow.Launcher.Infrastructure/Image/ThumbnailReader.cs b/Flow.Launcher.Infrastructure/Image/ThumbnailReader.cs
index 3b6f66bca..86f757eb8 100644
--- a/Flow.Launcher.Infrastructure/Image/ThumbnailReader.cs
+++ b/Flow.Launcher.Infrastructure/Image/ThumbnailReader.cs
@@ -38,6 +38,17 @@ namespace Flow.Launcher.Infrastructure.Image
 
         private const string UrlExtension = ".url";
 
+        /// <summary>
+        /// Obtains a BitmapSource thumbnail for the specified file.
+        /// </summary>
+        /// <remarks>
+        /// If the file is a Windows URL shortcut (".url"), the method attempts to resolve the shortcut's icon and use that for the thumbnail; otherwise it requests a thumbnail for the file path. The native HBITMAP used to create the BitmapSource is always released to avoid native memory leaks.
+        /// </remarks>
+        /// <param name="fileName">Path to the file (can be a regular file or a ".url" shortcut).</param>
+        /// <param name="width">Requested thumbnail width in pixels.</param>
+        /// <param name="height">Requested thumbnail height in pixels.</param>
+        /// <param name="options">Thumbnail extraction options (flags) controlling fallback and caching behavior.</param>
+        /// <returns>A BitmapSource representing the requested thumbnail.</returns>
         public static BitmapSource GetThumbnail(string fileName, int width, int height, ThumbnailOptions options)
         {
             HBITMAP hBitmap;
@@ -63,6 +74,21 @@ namespace Flow.Launcher.Infrastructure.Image
             }
         }
 
+        /// <summary>
+        /// Obtains a native HBITMAP for the specified file at the requested size using the Windows Shell image factory.
+        /// </summary>
+        /// <remarks>
+        /// If <paramref name="options"/> is <see cref="ThumbnailOptions.ThumbnailOnly"/> and thumbnail extraction fails
+        /// due to extraction errors or a missing path, the method falls back to requesting an icon (<see cref="ThumbnailOptions.IconOnly"/>).
+        /// The returned HBITMAP is a raw GDI handle; the caller is responsible for releasing it (e.g., via DeleteObject) to avoid native memory leaks.
+        /// </remarks>
+        /// <param name="fileName">Path to the file to thumbnail.</param>
+        /// <param name="width">Requested thumbnail width in pixels.</param>
+        /// <param name="height">Requested thumbnail height in pixels.</param>
+        /// <param name="options">Thumbnail request flags that control behavior (e.g., ThumbnailOnly, IconOnly).</param>
+        /// <returns>An HBITMAP handle containing the image. Caller must free the handle when finished.</returns>
+        /// <exception cref="COMException">If creating the shell item fails (HRESULT returned by SHCreateItemFromParsingName).</exception>
+        /// <exception cref="InvalidOperationException">If the shell item does not expose IShellItemImageFactory or if an unexpected error occurs while obtaining the image.</exception>
         private static unsafe HBITMAP GetHBitmap(string fileName, int width, int height, ThumbnailOptions options)
         {
             var retCode = PInvoke.SHCreateItemFromParsingName(
@@ -122,6 +148,19 @@ namespace Flow.Launcher.Infrastructure.Image
             return hBitmap;
         }
 
+        /// <summary>
+        /// Obtains an HBITMAP for a Windows .url shortcut by resolving its IconFile entry and delegating to GetHBitmap.
+        /// </summary>
+        /// <remarks>
+        /// The method parses the .url file as an INI, looks in the "InternetShortcut" section for the "IconFile" entry,
+        /// and requests a bitmap for that icon path. If no IconFile is present or any error occurs while reading or
+        /// resolving the icon, it falls back to requesting a thumbnail for the .url file itself.
+        /// </remarks>
+        /// <param name="fileName">Path to the .url shortcut file.</param>
+        /// <param name="width">Requested thumbnail width (pixels).</param>
+        /// <param name="height">Requested thumbnail height (pixels).</param>
+        /// <param name="options">ThumbnailOptions flags controlling extraction behavior.</param>
+        /// <returns>An HBITMAP containing the requested image; callers are responsible for freeing the native handle.</returns>
         private static unsafe HBITMAP GetHBitmapForUrlFile(string fileName, int width, int height, ThumbnailOptions options)
         {
             HBITMAP hBitmap;