Added exception documentation

Author: jamesmcroft

src/MADE.Collections/CollectionExtensions.cs

@@ -19,6 +19,8 @@ public static class CollectionExtensions
         /// <param name="item">The item to add.</param>
         /// <param name="condition">The condition required to add the item.</param>
         /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static void AddIf<T>(this IList<T> collection, T item, Func<bool> condition)
         {
             if (collection == null)
@@ -37,6 +39,33 @@ public static void AddIf<T>(this IList<T> collection, T item, Func<bool> conditi
             }
         }
 
+        /// <summary>
+        /// Removes the specified item from the collection based on the specified condition being true.
+        /// </summary>
+        /// <param name="collection">The collection to remove the item from.</param>
+        /// <param name="item">The item to remove.</param>
+        /// <param name="condition">The condition required to remove the item.</param>
+        /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
+        public static void RemoveIf<T>(this IList<T> collection, T item, Func<bool> condition)
+        {
+            if (collection == null)
+            {
+                throw new ArgumentNullException(nameof(collection));
+            }
+
+            if (condition == null)
+            {
+                throw new ArgumentNullException(nameof(condition));
+            }
+
+            if (condition())
+            {
+                collection.Remove(item);
+            }
+        }
+
         /// <summary>
         /// Updates an item within the collection.
         /// </summary>
@@ -146,6 +175,8 @@ public static void AddRange<T>(this ICollection<T> collection, IEnumerable<T> it
         /// <param name="itemsToAdd">The items to add.</param>
         /// <param name="condition">The condition required to add the items.</param>
         /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/>, <paramref name="itemsToAdd"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static void AddRangeIf<T>(
             this ICollection<T> collection,
             IEnumerable<T> itemsToAdd,
@@ -203,6 +234,8 @@ public static void RemoveRange<T>(this ICollection<T> collection, IEnumerable<T>
         /// <param name="itemsToRemove">The items to remove.</param>
         /// <param name="condition">The condition required to remove the items.</param>
         /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/>, <paramref name="itemsToRemove"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static void RemoveRangeIf<T>(
             this ICollection<T> collection,
             IEnumerable<T> itemsToRemove,
@@ -290,6 +323,7 @@ public static IEnumerable<T> TakeFrom<T>(this List<T> list, int startingIndex, i
         /// <param name="action">
         /// The action to perform.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static void ForEach<T>(this IEnumerable<T> collection, Action<T> action)
         {
             foreach (T item in collection)
@@ -308,7 +342,7 @@ public static void ForEach<T>(this IEnumerable<T> collection, Action<T> action)
         public static IEnumerable<IEnumerable<T>> Chunk<T>(this IEnumerable<T> source, int chunkSize = 25)
         {
             return source
-                .Select((v, i) => new {Index = i, Value = v})
+                .Select((v, i) => new { Index = i, Value = v })
                 .GroupBy(x => x.Index / chunkSize)
                 .Select(x => x.Select(v => v.Value));
         }
@@ -333,6 +367,7 @@ public static int InsertAtPotentialIndex<T>(this IList<T> source, T value, Func<
         /// <param name="predicate">The action to run to determine the position of the item based on the provided <paramref name="value"/> and an item in the collection.</param>
         /// <typeparam name="T">The type of items in the collection.</typeparam>
         /// <returns>The potential index of the item.</returns>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static int PotentialIndexOf<T>(this IList<T> source, T value, Func<T, T, bool> predicate)
         {
             var result = 0;

src/MADE.Collections/ObjectModel/ObservableItemCollection{T}.cs

@@ -27,6 +27,7 @@ public class ObservableItemCollection<T> : ObservableCollection<T>, IDisposable
         /// <summary>
         /// Initializes a new instance of the <see cref="ObservableItemCollection{T}"/> class that is empty and has a default initial capacity.
         /// </summary>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection()
         {
             base.CollectionChanged += (s, e) =>
@@ -46,6 +47,7 @@ public ObservableItemCollection()
         /// The collection whose elements are copied to the new list.
         /// </param>
         /// <exception cref="T:System.ArgumentNullException">The <paramref name="collection">collection</paramref> parameter cannot be null.</exception>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection(IEnumerable<T> collection)
             : base(collection)
         {
@@ -65,6 +67,7 @@ public ObservableItemCollection(IEnumerable<T> collection)
         /// The list whose elements are copied to the new list.
         /// </param>
         /// <exception cref="T:System.ArgumentNullException">The <paramref name="list">list</paramref> parameter cannot be null.</exception>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection(List<T> list)
             : base(list)
         {
@@ -93,6 +96,7 @@ public ObservableItemCollection(List<T> list)
         /// <param name="items">
         /// The objects to add to the end of the collection.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public void AddRange(IEnumerable<T> items)
         {
             this.CheckDisposed();
@@ -117,6 +121,7 @@ public void AddRange(IEnumerable<T> items)
         /// <param name="items">
         /// The objects to remove from the collection.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public void RemoveRange(IEnumerable<T> items)
         {
             this.CheckDisposed();

src/MADE.Data.Converters/BooleanToStringValueConverter.Windows.cs

@@ -80,7 +80,7 @@ public object Convert(object value, Type targetType, object parameter, string la
         /// <returns>The converted <see cref="bool"/> object.</returns>
         public object ConvertBack(object value, Type targetType, object parameter, string language)
         {
-            if (!(value is string b))
+            if (value is not string b)
             {
                 return value;
             }

src/MADE.Data.Converters/Constants/DateTimeConstants.cs

@@ -7,6 +7,11 @@ namespace MADE.Data.Converters.Constants
     /// </summary>
     public static class DateTimeConstants
     {
+        /// <summary>
+        /// Defines the minimum value for a <see cref="DateTime"/> object determined by Unix.
+        /// </summary>
+        public static readonly DateTime UnixEpoch = new(1970, 1, 1, 0, 0, 0);
+
         /// <summary>
         /// Defines the time at the end of a day.
         /// </summary>

src/MADE.Data.Converters/Extensions/DateTimeExtensions.cs

@@ -230,7 +230,7 @@ public static DateTime EndOfYear(this DateTime dateTime)
         /// </returns>
         public static DateTime? SetTime(this DateTime? dateTime, int hours, int minutes, int seconds, int milliseconds)
         {
-            return dateTime == null ? (DateTime?)null : SetTime(dateTime.Value, hours, minutes, seconds, milliseconds);
+            return dateTime == null ? null : SetTime(dateTime.Value, hours, minutes, seconds, milliseconds);
         }
 
         /// <summary>

src/MADE.Data.Converters/Extensions/StringExtensions.cs

@@ -166,7 +166,7 @@ public static int ToInt(this string value)
             }
 
             bool parsed = int.TryParse(value, out int intValue);
-            return parsed ? (int?)intValue : null;
+            return parsed ? intValue : null;
         }
 
         /// <summary>
@@ -226,7 +226,7 @@ public static float ToFloat(this string value)
             }
 
             bool parsed = float.TryParse(value, out float floatValue);
-            return parsed ? (float?)floatValue : null;
+            return parsed ? floatValue : null;
         }
 
         /// <summary>
@@ -266,7 +266,7 @@ public static double ToDouble(this string value)
             }
 
             bool parsed = double.TryParse(value, out double doubleValue);
-            return parsed ? (double?)doubleValue : null;
+            return parsed ? doubleValue : null;
         }
     }
 }

src/MADE.Data.EFCore/Converters/UtcDateTimeConverter.cs

@@ -12,7 +12,7 @@ namespace MADE.Data.EFCore.Converters
     public static class UtcDateTimeConverter
     {
         internal static readonly ValueConverter<DateTime, DateTime> UtcConverter =
-            new ValueConverter<DateTime, DateTime>(
+            new(
                 value => value,
                 value => DateTime.SpecifyKind(value, DateTimeKind.Utc));
 

src/MADE.Data.EFCore/Extensions/DbContextExtensions.cs

@@ -26,6 +26,7 @@ public static class DbContextExtensions
         /// <exception cref="DbUpdateConcurrencyException">A concurrency violation is encountered while saving to the database.
         ///                 A concurrency violation occurs when an unexpected number of rows are affected during save.
         ///                 This is usually because the data in the database has been modified since it was loaded into memory.</exception>
+        /// <exception cref="OperationCanceledException">If the <see cref="CancellationToken" /> is canceled.</exception>
         public static async Task UpdateAsync<T>(
             this DbContext context,
             T entity,
@@ -61,7 +62,7 @@ public static void SetEntityDates(this DbContext context)
                 .Entries()
                 .Where(
                     entry => entry.Entity is IEntityBase &&
-                             (entry.State == EntityState.Added || entry.State == EntityState.Modified));
+                             entry.State is EntityState.Added or EntityState.Modified);
 
             DateTime now = DateTime.UtcNow;
 
@@ -86,6 +87,8 @@ public static void SetEntityDates(this DbContext context)
         /// <returns>
         ///  True if the changes saved successfully; otherwise, false.
         /// </returns>
+        /// <exception cref="OperationCanceledException">If the <see cref="CancellationToken" /> is canceled.</exception>
+        /// <exception cref="Exception">Potentially thrown by the <paramref name="onError"/> delegate callback.</exception>
         public static async Task<bool> TrySaveChangesAsync(
             this DbContext context,
             Action<Exception> onError = null,
@@ -112,6 +115,7 @@ public static async Task<bool> TrySaveChangesAsync(
         /// <param name="onError">An exception for handling the exception thrown, for example, event logging.</param>
         /// <typeparam name="TContext">The type of data context.</typeparam>
         /// <returns>True if the action ran successfully; otherwise, false.</returns>
+        /// <exception cref="Exception">Potentially thrown by the <paramref name="onError"/> delegate callback.</exception>
         public static async Task<bool> TryAsync<TContext>(
             this TContext context,
             Func<TContext, Task> action,

src/MADE.Data.Validation/Extensions/DateTimeExtensions.cs

@@ -26,7 +26,7 @@ public static bool IsInRange(this DateTime date, DateTime from, DateTime to)
         /// <returns>True if the day of week is between Monday and Friday; otherwise, false.</returns>
         public static bool IsWeekday(this DateTime date)
         {
-            return date.DayOfWeek >= DayOfWeek.Monday && date.DayOfWeek <= DayOfWeek.Friday;
+            return date.DayOfWeek is >= DayOfWeek.Monday and <= DayOfWeek.Friday;
         }
 
         /// <summary>
@@ -36,7 +36,7 @@ public static bool IsWeekday(this DateTime date)
         /// <returns>True if the day of week is Saturday or Sunday; otherwise, false.</returns>
         public static bool IsWeekend(this DateTime date)
         {
-            return date.DayOfWeek == DayOfWeek.Saturday || date.DayOfWeek == DayOfWeek.Sunday;
+            return date.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday;
         }
     }
 }

src/MADE.Data.Validation/Extensions/MathExtensions.cs

@@ -3,6 +3,7 @@
 
 namespace MADE.Data.Validation.Extensions
 {
+    using System;
     using MADE.Data.Validation.Exceptions;
 
     /// <summary>
@@ -26,7 +27,7 @@ public static class MathExtensions
         /// </returns>
         public static bool IsZero(this double value)
         {
-            return System.Math.Abs(value) < Epsilon;
+            return Math.Abs(value) < Epsilon;
         }
 
         /// <summary>
@@ -40,7 +41,7 @@ public static bool IsZero(this double value)
         /// </returns>
         public static bool IsZero(this float value)
         {
-            return System.Math.Abs(value) < Epsilon;
+            return Math.Abs(value) < Epsilon;
         }
 
         /// <summary>
@@ -55,14 +56,15 @@ public static bool IsZero(this float value)
         /// <returns>
         /// True if the values are close; otherwise, false.
         /// </returns>
+        /// <exception cref="OverflowException">Thrown if the value equals <see cref="int.MinValue"></see>.</exception>
         public static bool IsCloseTo(this int value, int compare)
         {
-            if (System.Math.Abs(value - compare) < 1)
+            if (Math.Abs(value - compare) < 1)
             {
                 return true;
             }
 
-            double a = (System.Math.Abs(value) + System.Math.Abs(compare) + 10.0) * Epsilon;
+            double a = (Math.Abs(value) + Math.Abs(compare) + 10.0) * Epsilon;
             int b = value - compare;
             return -a < b && a > b;
         }
@@ -81,12 +83,12 @@ public static bool IsCloseTo(this int value, int compare)
         /// </returns>
         public static bool IsCloseTo(this double value, double compare)
         {
-            if (System.Math.Abs(value - compare) < Epsilon)
+            if (Math.Abs(value - compare) < Epsilon)
             {
                 return true;
             }
 
-            double a = (System.Math.Abs(value) + System.Math.Abs(compare) + 10.0) * Epsilon;
+            double a = (Math.Abs(value) + Math.Abs(compare) + 10.0) * Epsilon;
             double b = value - compare;
             return -a < b && a > b;
         }
@@ -110,12 +112,12 @@ public static bool IsCloseTo(this double? value, double? compare)
                 return false;
             }
 
-            if (System.Math.Abs(value.Value - compare.Value) < Epsilon)
+            if (Math.Abs(value.Value - compare.Value) < Epsilon)
             {
                 return true;
             }
 
-            double a = (System.Math.Abs(value.Value) + System.Math.Abs(compare.Value) + 10.0) * Epsilon;
+            double a = (Math.Abs(value.Value) + Math.Abs(compare.Value) + 10.0) * Epsilon;
             double? b = value - compare;
             return -a < b && a > b;
         }
@@ -134,12 +136,12 @@ public static bool IsCloseTo(this double? value, double? compare)
         /// </returns>
         public static bool IsCloseTo(this float value, float compare)
         {
-            if (System.Math.Abs(value - compare) < Epsilon)
+            if (Math.Abs(value - compare) < Epsilon)
             {
                 return true;
             }
 
-            double a = (System.Math.Abs(value) + System.Math.Abs(compare) + 10.0) * Epsilon;
+            double a = (Math.Abs(value) + Math.Abs(compare) + 10.0) * Epsilon;
             float b = value - compare;
             return -a < b && a > b;
         }
@@ -163,12 +165,12 @@ public static bool IsCloseTo(this float? value, float? compare)
                 return false;
             }
 
-            if (System.Math.Abs(value.Value - compare.Value) < Epsilon)
+            if (Math.Abs(value.Value - compare.Value) < Epsilon)
             {
                 return true;
             }
 
-            double a = (System.Math.Abs(value.Value) + System.Math.Abs(compare.Value) + 10.0) * Epsilon;
+            double a = (Math.Abs(value.Value) + Math.Abs(compare.Value) + 10.0) * Epsilon;
             float? b = value - compare;
             return -a < b && a > b;
         }