From 7524b7809cd9db1739b178001e92cb2f33d73cda Mon Sep 17 00:00:00 2001
From: Laura Neto <12862535+lauraneto@users.noreply.github.com>
Date: Sat, 9 Oct 2021 10:28:25 +0200
Subject: [PATCH] Added missing documentation to Image Cropper Extensions

---
 .../FriendlyImageCropperTemplateExtensions.cs | 19 +++++++
 .../ImageCropperTemplateCoreExtensions.cs     | 50 +++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/src/Umbraco.Web.Common/Extensions/FriendlyImageCropperTemplateExtensions.cs b/src/Umbraco.Web.Common/Extensions/FriendlyImageCropperTemplateExtensions.cs
index cbce607b326e..c59e7b112625 100644
--- a/src/Umbraco.Web.Common/Extensions/FriendlyImageCropperTemplateExtensions.cs
+++ b/src/Umbraco.Web.Common/Extensions/FriendlyImageCropperTemplateExtensions.cs
@@ -32,6 +32,15 @@ public static string GetCropUrl(
             UrlMode urlMode = UrlMode.Default) =>
             mediaItem.GetCropUrl(cropAlias, ImageUrlGenerator, PublishedValueFallback, PublishedUrlProvider, urlMode);
 
+        /// <summary>
+        /// Gets the underlying image processing service URL by the crop alias (from the "umbracoFile" property alias in the MediaWithCrops content item) on the MediaWithCrops item.
+        /// </summary>
+        /// <param name="mediaWithCrops">The MediaWithCrops item.</param>
+        /// <param name="cropAlias">The crop alias e.g. thumbnail.</param>
+        /// <param name="urlMode">The url mode.</param>
+        /// <returns>
+        /// The URL of the cropped image.
+        /// </returns>
         public static string GetCropUrl(this MediaWithCrops mediaWithCrops, string cropAlias, UrlMode urlMode = UrlMode.Default)
             => ImageCropperTemplateCoreExtensions.GetCropUrl(mediaWithCrops, cropAlias, ImageUrlGenerator, PublishedValueFallback, PublishedUrlProvider, urlMode);
 
@@ -69,6 +78,16 @@ public static string GetCropUrl(
             UrlMode urlMode = UrlMode.Default) =>
             mediaItem.GetCropUrl(propertyAlias, cropAlias, ImageUrlGenerator, PublishedValueFallback, PublishedUrlProvider, urlMode);
 
+        /// <summary>
+        /// Gets the underlying image processing service URL by the crop alias using the specified property containing the image cropper JSON data on the MediaWithCrops content item.
+        /// </summary>
+        /// <param name="mediaWithCrops">The MediaWithCrops item.</param>
+        /// <param name="propertyAlias">The property alias of the property containing the JSON data e.g. umbracoFile.</param>
+        /// <param name="cropAlias">The crop alias e.g. thumbnail.</param>
+        /// <param name="urlMode">The url mode.</param>
+        /// <returns>
+        /// The URL of the cropped image.
+        /// </returns>
         public static string GetCropUrl(this MediaWithCrops mediaWithCrops, string propertyAlias, string cropAlias, UrlMode urlMode = UrlMode.Default)
             => ImageCropperTemplateCoreExtensions.GetCropUrl(mediaWithCrops, propertyAlias, cropAlias, ImageUrlGenerator, PublishedValueFallback, PublishedUrlProvider, urlMode);
 
diff --git a/src/Umbraco.Web.Common/Extensions/ImageCropperTemplateCoreExtensions.cs b/src/Umbraco.Web.Common/Extensions/ImageCropperTemplateCoreExtensions.cs
index a3e96ebebb47..f335a81ae78a 100644
--- a/src/Umbraco.Web.Common/Extensions/ImageCropperTemplateCoreExtensions.cs
+++ b/src/Umbraco.Web.Common/Extensions/ImageCropperTemplateCoreExtensions.cs
@@ -32,6 +32,18 @@ public static string GetCropUrl(
             IPublishedUrlProvider publishedUrlProvider,
             UrlMode urlMode = UrlMode.Default) => mediaItem.GetCropUrl(imageUrlGenerator, publishedValueFallback, publishedUrlProvider, cropAlias: cropAlias, useCropDimensions: true, urlMode: urlMode);
 
+        /// <summary>
+        /// Gets the underlying image processing service URL by the crop alias (from the "umbracoFile" property alias in the MediaWithCrops content item) on the MediaWithCrops item.
+        /// </summary>
+        /// <param name="mediaWithCrops">The MediaWithCrops item.</param>
+        /// <param name="cropAlias">The crop alias e.g. thumbnail.</param>
+        /// <param name="imageUrlGenerator">The image URL generator.</param>
+        /// <param name="publishedValueFallback">The published value fallback.</param>
+        /// <param name="publishedUrlProvider">The published URL provider.</param>
+        /// <param name="urlMode">The url mode.</param>
+        /// <returns>
+        /// The URL of the cropped image.
+        /// </returns>
         public static string GetCropUrl(
             this MediaWithCrops mediaWithCrops,
             string cropAlias,
@@ -84,6 +96,19 @@ public static string GetCropUrl(
             IPublishedUrlProvider publishedUrlProvider,
             UrlMode urlMode = UrlMode.Default) => mediaItem.GetCropUrl(imageUrlGenerator, publishedValueFallback, publishedUrlProvider, propertyAlias: propertyAlias, cropAlias: cropAlias, useCropDimensions: true, urlMode: urlMode);
 
+        /// <summary>
+        /// Gets the underlying image processing service URL by the crop alias using the specified property containing the image cropper JSON data on the MediaWithCrops content item.
+        /// </summary>
+        /// <param name="mediaWithCrops">The MediaWithCrops item.</param>
+        /// <param name="propertyAlias">The property alias of the property containing the JSON data e.g. umbracoFile.</param>
+        /// <param name="cropAlias">The crop alias e.g. thumbnail.</param>
+        /// <param name="imageUrlGenerator">The image URL generator.</param>
+        /// <param name="publishedValueFallback">The published value fallback.</param>
+        /// <param name="publishedUrlProvider">The published URL provider.</param>
+        /// <param name="urlMode">The url mode.</param>
+        /// <returns>
+        /// The URL of the cropped image.
+        /// </returns>
         public static string GetCropUrl(this MediaWithCrops mediaWithCrops,
             IPublishedValueFallback publishedValueFallback,
             IPublishedUrlProvider publishedUrlProvider,
@@ -135,6 +160,31 @@ public static string GetCropUrl(
              string furtherOptions = null,
              UrlMode urlMode = UrlMode.Default) => mediaItem.GetCropUrl(imageUrlGenerator, publishedValueFallback, publishedUrlProvider, null, false, width, height, propertyAlias, cropAlias, quality, imageCropMode, imageCropAnchor, preferFocalPoint, useCropDimensions, cacheBuster, furtherOptions, urlMode);
 
+        /// <summary>
+        /// Gets the underlying image processing service URL from the MediaWithCrops item.
+        /// </summary>
+        /// <param name="mediaWithCrops">The MediaWithCrops item.</param>
+        /// <param name="imageUrlGenerator">The image URL generator.</param>
+        /// <param name="publishedValueFallback">The published value fallback.</param>
+        /// <param name="publishedUrlProvider">The published URL provider.</param>
+        /// <param name="width">The width of the output image.</param>
+        /// <param name="height">The height of the output image.</param>
+        /// <param name="propertyAlias">Property alias of the property containing the JSON data.</param>
+        /// <param name="cropAlias">The crop alias.</param>
+        /// <param name="quality">Quality percentage of the output image.</param>
+        /// <param name="imageCropMode">The image crop mode.</param>
+        /// <param name="imageCropAnchor">The image crop anchor.</param>
+        /// <param name="preferFocalPoint">Use focal point, to generate an output image using the focal point instead of the predefined crop.</param>
+        /// <param name="useCropDimensions">Use crop dimensions to have the output image sized according to the predefined crop sizes, this will override the width and height parameters.</param>
+        /// <param name="cacheBuster">Add a serialized date of the last edit of the item to ensure client cache refresh when updated.</param>
+        /// <param name="furtherOptions">These are any query string parameters (formatted as query strings) that ImageProcessor supports. For example:
+        /// <example><![CDATA[
+        /// furtherOptions: "bgcolor=fff"
+        /// ]]></example></param>
+        /// <param name="urlMode">The url mode.</param>
+        /// <returns>
+        /// The URL of the cropped image.
+        /// </returns>
         public static string GetCropUrl(
              this MediaWithCrops mediaWithCrops,
              IImageUrlGenerator imageUrlGenerator,