From 8efd935beec138afa49be42b875295d23cede393 Mon Sep 17 00:00:00 2001
From: tobitege <10787084+tobitege@users.noreply.github.com>
Date: Sun, 7 Jun 2026 08:31:36 +0200
Subject: [PATCH] Fix release CI warnings

Add XML documentation for the image converter APIs reported by CI.
Suppress CS1591 during generated XML documentation builds so existing undocumented public APIs do not flood release builds.
Pin Windows GitHub Actions jobs to windows-2022 to avoid the upcoming windows-latest image migration notice.
---
 .github/workflows/ci.yml                      |   2 +-
 .github/workflows/release.yml                 |   2 +-
 Directory.Build.targets                       |   6 +
 .../ImageConverter.cs                         |  17 +-
 .../ImageProcessingOptionsBuilder.cs          | 229 +++++++++++++++++-
 5 files changed, 252 insertions(+), 4 deletions(-)
 create mode 100644 Directory.Build.targets

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4325175..e84b712 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,7 @@ on:
 
 jobs:
   build:
-    runs-on: windows-latest
+    runs-on: windows-2022
     steps:
       - uses: actions/checkout@v6
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fda6da8..060f665 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -39,7 +39,7 @@ jobs:
 
   build-desktop:
     needs: validate
-    runs-on: windows-latest
+    runs-on: windows-2022
     permissions:
       contents: read
 
diff --git a/Directory.Build.targets b/Directory.Build.targets
new file mode 100644
index 0000000..cf89a6d
--- /dev/null
+++ b/Directory.Build.targets
@@ -0,0 +1,6 @@
+<Project>
+  <PropertyGroup Condition="'$(GenerateDocumentationFile)'=='true'">
+    <!-- XML docs are generated for release packages, but not every public API is documented yet. -->
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+  </PropertyGroup>
+</Project>
diff --git a/OpenSourceToolkit.Converters/ImageConverter.cs b/OpenSourceToolkit.Converters/ImageConverter.cs
index aaaea13..e7f1d7c 100644
--- a/OpenSourceToolkit.Converters/ImageConverter.cs
+++ b/OpenSourceToolkit.Converters/ImageConverter.cs
@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Drawing;
 using System.Drawing.Imaging;
 using System.IO;
@@ -6,9 +6,18 @@
 
 namespace OpenSourceToolkit.Converters
 {
+    /// <summary>
+    /// Provides basic image conversion helpers for file and byte-array inputs.
+    /// </summary>
     [SupportedOSPlatform("windows")]
     public static class ImageConverter
     {
+        /// <summary>
+        /// Converts an image file to the specified output format.
+        /// </summary>
+        /// <param name="inputPath">Path to the source image file.</param>
+        /// <param name="outputPath">Path where the converted image should be saved.</param>
+        /// <param name="format">Image format to use for the output file.</param>
         public static void Convert(string inputPath, string outputPath, ImageFormat format)
         {
             using (var image = Image.FromFile(inputPath))
@@ -17,6 +26,12 @@ public static void Convert(string inputPath, string outputPath, ImageFormat form
             }
         }
 
+        /// <summary>
+        /// Converts image bytes to the specified output format.
+        /// </summary>
+        /// <param name="inputBytes">Source image bytes.</param>
+        /// <param name="format">Image format to use for the converted bytes.</param>
+        /// <returns>The converted image bytes.</returns>
         public static byte[] Convert(byte[] inputBytes, ImageFormat format)
         {
             using (var inputStream = new MemoryStream(inputBytes))
diff --git a/OpenSourceToolkit.Converters/ImageProcessingOptionsBuilder.cs b/OpenSourceToolkit.Converters/ImageProcessingOptionsBuilder.cs
index 0475264..0100dd0 100644
--- a/OpenSourceToolkit.Converters/ImageProcessingOptionsBuilder.cs
+++ b/OpenSourceToolkit.Converters/ImageProcessingOptionsBuilder.cs
@@ -1,4 +1,4 @@
-namespace OpenSourceToolkit.Converters
+namespace OpenSourceToolkit.Converters
 {
     /// <summary>
     /// Fluent builder for ImageProcessingOptions.
@@ -12,18 +12,35 @@ public class ImageProcessingOptionsBuilder
         // Output Settings
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Sets the output image format.
+        /// </summary>
+        /// <param name="format">Output format name, such as "png" or "jpg".</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithFormat(string format)
         {
             _options.Format = format;
             return this;
         }
 
+        /// <summary>
+        /// Sets the output image quality.
+        /// </summary>
+        /// <param name="quality">Output quality value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithQuality(int quality)
         {
             _options.Quality = quality;
             return this;
         }
 
+        /// <summary>
+        /// Sets resize options for the output image.
+        /// </summary>
+        /// <param name="width">Optional target width.</param>
+        /// <param name="height">Optional target height.</param>
+        /// <param name="maintainAspectRatio">Whether to preserve the original aspect ratio.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithResize(int? width, int? height, bool maintainAspectRatio = true)
         {
             _options.Width = width;
@@ -36,24 +53,46 @@ public ImageProcessingOptionsBuilder WithResize(int? width, int? height, bool ma
         // Adjustments
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Sets the brightness adjustment.
+        /// </summary>
+        /// <param name="brightness">Brightness adjustment value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithBrightness(int brightness)
         {
             _options.Brightness = brightness;
             return this;
         }
 
+        /// <summary>
+        /// Sets the contrast adjustment.
+        /// </summary>
+        /// <param name="contrast">Contrast adjustment value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithContrast(int contrast)
         {
             _options.Contrast = contrast;
             return this;
         }
 
+        /// <summary>
+        /// Sets the saturation adjustment.
+        /// </summary>
+        /// <param name="saturation">Saturation adjustment value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithSaturation(int saturation)
         {
             _options.Saturation = saturation;
             return this;
         }
 
+        /// <summary>
+        /// Sets brightness, contrast, and saturation adjustments.
+        /// </summary>
+        /// <param name="brightness">Brightness adjustment value.</param>
+        /// <param name="contrast">Contrast adjustment value.</param>
+        /// <param name="saturation">Saturation adjustment value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithAdjustments(int brightness, int contrast, int saturation)
         {
             _options.Brightness = brightness;
@@ -66,18 +105,33 @@ public ImageProcessingOptionsBuilder WithAdjustments(int brightness, int contras
         // Filters
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables or disables grayscale conversion.
+        /// </summary>
+        /// <param name="enabled">Whether grayscale conversion is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithGrayscale(bool enabled = true)
         {
             _options.Grayscale = enabled;
             return this;
         }
 
+        /// <summary>
+        /// Enables or disables sepia conversion.
+        /// </summary>
+        /// <param name="enabled">Whether sepia conversion is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithSepia(bool enabled = true)
         {
             _options.Sepia = enabled;
             return this;
         }
 
+        /// <summary>
+        /// Enables or disables color inversion.
+        /// </summary>
+        /// <param name="enabled">Whether color inversion is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithInvert(bool enabled = true)
         {
             _options.Invert = enabled;
@@ -88,12 +142,22 @@ public ImageProcessingOptionsBuilder WithInvert(bool enabled = true)
         // Blur / Sharpen
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Sets the blur radius.
+        /// </summary>
+        /// <param name="radius">Blur radius value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithBlur(int radius)
         {
             _options.BlurRadius = radius;
             return this;
         }
 
+        /// <summary>
+        /// Sets the sharpen amount.
+        /// </summary>
+        /// <param name="amount">Sharpen amount value.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithSharpen(int amount)
         {
             _options.SharpenAmount = amount;
@@ -104,24 +168,46 @@ public ImageProcessingOptionsBuilder WithSharpen(int amount)
         // Transform
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Sets the rotation angle.
+        /// </summary>
+        /// <param name="angle">Rotation angle in degrees.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithRotation(int angle)
         {
             _options.RotationAngle = angle;
             return this;
         }
 
+        /// <summary>
+        /// Enables or disables horizontal flipping.
+        /// </summary>
+        /// <param name="enabled">Whether horizontal flipping is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithFlipHorizontal(bool enabled = true)
         {
             _options.FlipHorizontal = enabled;
             return this;
         }
 
+        /// <summary>
+        /// Enables or disables vertical flipping.
+        /// </summary>
+        /// <param name="enabled">Whether vertical flipping is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithFlipVertical(bool enabled = true)
         {
             _options.FlipVertical = enabled;
             return this;
         }
 
+        /// <summary>
+        /// Sets rotation and flip options.
+        /// </summary>
+        /// <param name="rotationAngle">Rotation angle in degrees.</param>
+        /// <param name="flipHorizontal">Whether horizontal flipping is enabled.</param>
+        /// <param name="flipVertical">Whether vertical flipping is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithTransform(int rotationAngle, bool flipHorizontal, bool flipVertical)
         {
             _options.RotationAngle = rotationAngle;
@@ -134,6 +220,14 @@ public ImageProcessingOptionsBuilder WithTransform(int rotationAngle, bool flipH
         // Crop
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables cropping and sets the crop rectangle.
+        /// </summary>
+        /// <param name="x">Crop origin on the x-axis.</param>
+        /// <param name="y">Crop origin on the y-axis.</param>
+        /// <param name="width">Crop width.</param>
+        /// <param name="height">Crop height.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithCrop(int x, int y, int width, int height)
         {
             _options.CropEnabled = true;
@@ -144,6 +238,10 @@ public ImageProcessingOptionsBuilder WithCrop(int x, int y, int width, int heigh
             return this;
         }
 
+        /// <summary>
+        /// Disables cropping.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithCropDisabled()
         {
             _options.CropEnabled = false;
@@ -154,6 +252,16 @@ public ImageProcessingOptionsBuilder WithCropDisabled()
         // Watermark
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables a text watermark and sets its options.
+        /// </summary>
+        /// <param name="text">Watermark text.</param>
+        /// <param name="position">Watermark position.</param>
+        /// <param name="opacity">Watermark opacity.</param>
+        /// <param name="fontSize">Watermark font size.</param>
+        /// <param name="color">Watermark color.</param>
+        /// <param name="padding">Watermark padding.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithTextWatermark(
             string text,
             WatermarkPosition position = WatermarkPosition.BottomRight,
@@ -173,6 +281,14 @@ public ImageProcessingOptionsBuilder WithTextWatermark(
             return this;
         }
 
+        /// <summary>
+        /// Enables an image watermark and sets its options.
+        /// </summary>
+        /// <param name="imageBytes">Watermark image bytes.</param>
+        /// <param name="position">Watermark position.</param>
+        /// <param name="opacity">Watermark opacity.</param>
+        /// <param name="padding">Watermark padding.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithImageWatermark(
             byte[] imageBytes,
             WatermarkPosition position = WatermarkPosition.BottomRight,
@@ -188,6 +304,10 @@ public ImageProcessingOptionsBuilder WithImageWatermark(
             return this;
         }
 
+        /// <summary>
+        /// Disables watermarking.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithWatermarkDisabled()
         {
             _options.WatermarkEnabled = false;
@@ -198,12 +318,23 @@ public ImageProcessingOptionsBuilder WithWatermarkDisabled()
         // Phase 3 Effects
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables or disables automatic image enhancement.
+        /// </summary>
+        /// <param name="enabled">Whether automatic enhancement is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithAutoEnhance(bool enabled = true)
         {
             _options.AutoEnhance = enabled;
             return this;
         }
 
+        /// <summary>
+        /// Enables vignette and sets its options.
+        /// </summary>
+        /// <param name="radius">Vignette radius.</param>
+        /// <param name="softness">Vignette softness.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithVignette(int radius = 50, int softness = 50)
         {
             _options.Vignette = true;
@@ -212,12 +343,21 @@ public ImageProcessingOptionsBuilder WithVignette(int radius = 50, int softness
             return this;
         }
 
+        /// <summary>
+        /// Disables vignette.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithVignetteDisabled()
         {
             _options.Vignette = false;
             return this;
         }
 
+        /// <summary>
+        /// Enables posterization and sets the number of color levels.
+        /// </summary>
+        /// <param name="levels">Number of posterization levels.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithPosterize(int levels = 4)
         {
             _options.Posterize = true;
@@ -225,12 +365,21 @@ public ImageProcessingOptionsBuilder WithPosterize(int levels = 4)
             return this;
         }
 
+        /// <summary>
+        /// Disables posterization.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithPosterizeDisabled()
         {
             _options.Posterize = false;
             return this;
         }
 
+        /// <summary>
+        /// Enables edge detection and sets its radius.
+        /// </summary>
+        /// <param name="radius">Edge detection radius.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithEdgeDetect(int radius = 1)
         {
             _options.EdgeDetect = true;
@@ -238,6 +387,10 @@ public ImageProcessingOptionsBuilder WithEdgeDetect(int radius = 1)
             return this;
         }
 
+        /// <summary>
+        /// Disables edge detection.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithEdgeDetectDisabled()
         {
             _options.EdgeDetect = false;
@@ -248,6 +401,12 @@ public ImageProcessingOptionsBuilder WithEdgeDetectDisabled()
         // Background Removal
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables background removal and sets its options.
+        /// </summary>
+        /// <param name="backgroundColor">Background color to remove.</param>
+        /// <param name="tolerance">Color matching tolerance.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithBackgroundRemoval(string backgroundColor = "transparent", int tolerance = 10)
         {
             _options.RemoveBackground = true;
@@ -256,6 +415,10 @@ public ImageProcessingOptionsBuilder WithBackgroundRemoval(string backgroundColo
             return this;
         }
 
+        /// <summary>
+        /// Disables background removal.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithBackgroundRemovalDisabled()
         {
             _options.RemoveBackground = false;
@@ -266,6 +429,11 @@ public ImageProcessingOptionsBuilder WithBackgroundRemovalDisabled()
         // Metadata
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables or disables metadata stripping.
+        /// </summary>
+        /// <param name="enabled">Whether metadata stripping is enabled.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithStripMetadata(bool enabled = true)
         {
             _options.StripMetadata = enabled;
@@ -276,6 +444,11 @@ public ImageProcessingOptionsBuilder WithStripMetadata(bool enabled = true)
         // ICO Multi-size
         // ═══════════════════════════════════════════════════════════════════════════
 
+        /// <summary>
+        /// Enables multi-size ICO generation.
+        /// </summary>
+        /// <param name="sizes">Optional ICO sizes to generate.</param>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithMultiSizeIco(int[] sizes = null)
         {
             _options.GenerateMultiSizeIco = true;
@@ -286,6 +459,10 @@ public ImageProcessingOptionsBuilder WithMultiSizeIco(int[] sizes = null)
             return this;
         }
 
+        /// <summary>
+        /// Disables multi-size ICO generation.
+        /// </summary>
+        /// <returns>The current builder instance.</returns>
         public ImageProcessingOptionsBuilder WithMultiSizeIcoDisabled()
         {
             _options.GenerateMultiSizeIco = false;
@@ -299,6 +476,7 @@ public ImageProcessingOptionsBuilder WithMultiSizeIcoDisabled()
         /// <summary>
         /// Builds and returns the configured ImageProcessingOptions.
         /// </summary>
+        /// <returns>The configured image processing options.</returns>
         public ImageProcessingOptions Build()
         {
             return _options;
@@ -307,6 +485,7 @@ public ImageProcessingOptions Build()
         /// <summary>
         /// Creates a new builder instance.
         /// </summary>
+        /// <returns>A new image processing options builder.</returns>
         public static ImageProcessingOptionsBuilder Create()
         {
             return new ImageProcessingOptionsBuilder();
@@ -315,6 +494,7 @@ public static ImageProcessingOptionsBuilder Create()
         /// <summary>
         /// Creates a builder pre-configured for preview (PNG format, no resize/output settings).
         /// </summary>
+        /// <returns>A builder configured for preview output.</returns>
         public static ImageProcessingOptionsBuilder ForPreview()
         {
             return new ImageProcessingOptionsBuilder().WithFormat("png");
@@ -323,6 +503,9 @@ public static ImageProcessingOptionsBuilder ForPreview()
         /// <summary>
         /// Creates a builder pre-configured for batch conversion (format and resize only).
         /// </summary>
+        /// <param name="format">Output format name.</param>
+        /// <param name="quality">Output quality value.</param>
+        /// <returns>A builder configured for batch conversion.</returns>
         public static ImageProcessingOptionsBuilder ForBatch(string format, int quality = 90)
         {
             return new ImageProcessingOptionsBuilder()
@@ -334,7 +517,51 @@ public static ImageProcessingOptionsBuilder ForBatch(string format, int quality
         /// Creates options for single image editing with all effect parameters.
         /// </summary>
         /// <param name="format">Output format (e.g., "png", "jpg")</param>
+        /// <param name="quality">Output quality value.</param>
         /// <param name="includeResizeAndOutput">Include resize/format/quality settings (false for preview)</param>
+        /// <param name="resizeEnabled">Whether resize settings are enabled.</param>
+        /// <param name="resizeWidth">Optional resize width.</param>
+        /// <param name="resizeHeight">Optional resize height.</param>
+        /// <param name="maintainAspectRatio">Whether to preserve the original aspect ratio.</param>
+        /// <param name="brightness">Brightness adjustment value.</param>
+        /// <param name="contrast">Contrast adjustment value.</param>
+        /// <param name="saturation">Saturation adjustment value.</param>
+        /// <param name="grayscale">Whether grayscale conversion is enabled.</param>
+        /// <param name="sepia">Whether sepia conversion is enabled.</param>
+        /// <param name="invert">Whether color inversion is enabled.</param>
+        /// <param name="blurRadius">Blur radius value.</param>
+        /// <param name="sharpenAmount">Sharpen amount value.</param>
+        /// <param name="rotationAngle">Rotation angle in degrees.</param>
+        /// <param name="flipHorizontal">Whether horizontal flipping is enabled.</param>
+        /// <param name="flipVertical">Whether vertical flipping is enabled.</param>
+        /// <param name="cropEnabled">Whether cropping is enabled.</param>
+        /// <param name="cropX">Crop origin on the x-axis.</param>
+        /// <param name="cropY">Crop origin on the y-axis.</param>
+        /// <param name="cropWidth">Crop width.</param>
+        /// <param name="cropHeight">Crop height.</param>
+        /// <param name="watermarkEnabled">Whether watermarking is enabled.</param>
+        /// <param name="watermarkText">Optional watermark text.</param>
+        /// <param name="watermarkImageBytes">Optional watermark image bytes.</param>
+        /// <param name="watermarkPosition">Watermark position.</param>
+        /// <param name="watermarkOpacity">Watermark opacity.</param>
+        /// <param name="watermarkFontSize">Watermark font size.</param>
+        /// <param name="watermarkColor">Watermark color.</param>
+        /// <param name="watermarkPadding">Watermark padding.</param>
+        /// <param name="autoEnhance">Whether automatic enhancement is enabled.</param>
+        /// <param name="vignette">Whether vignette is enabled.</param>
+        /// <param name="vignetteRadius">Vignette radius.</param>
+        /// <param name="vignetteSoftness">Vignette softness.</param>
+        /// <param name="posterize">Whether posterization is enabled.</param>
+        /// <param name="posterizeLevels">Number of posterization levels.</param>
+        /// <param name="edgeDetect">Whether edge detection is enabled.</param>
+        /// <param name="edgeDetectRadius">Edge detection radius.</param>
+        /// <param name="removeBackground">Whether background removal is enabled.</param>
+        /// <param name="backgroundColor">Background color to remove.</param>
+        /// <param name="backgroundTolerance">Color matching tolerance.</param>
+        /// <param name="stripMetadata">Whether metadata stripping is enabled.</param>
+        /// <param name="generateMultiSizeIco">Whether multi-size ICO generation is enabled.</param>
+        /// <param name="icoSizes">Optional ICO sizes to generate.</param>
+        /// <returns>The configured image processing options.</returns>
         public static ImageProcessingOptions BuildSingleImageOptions(
             // Output settings
             string format,