Fix API Checks, Add paragraphs to comments. (#759)

src/DynamicData.Tests/API/ApiApprovalTests.cs

@@ -1,4 +1,5 @@
 using System.Diagnostics.CodeAnalysis;
+using System.Threading.Tasks;
 using VerifyXunit;
 using Xunit;
 
@@ -9,12 +10,12 @@ namespace DynamicData.APITests
     /// </summary>
     [ExcludeFromCodeCoverage]
     [UsesVerify]
-    public class ApiApprovalTests : ApiApprovalBase
+    public class ApiApprovalTests
     {
         /// <summary>
-        /// Tests to make sure the DynamicData project is approved.
+        /// Tests to make sure the API of DynamicData project is approved.
         /// </summary>
         [Fact]
-        public void DynamicDataTests() => CheckApproval(typeof(VirtualRequest).Assembly);
+        public Task DynamicDataTests() => typeof(VirtualRequest).Assembly.CheckApproval(["DynamicData"]);
     }
 }

src/DynamicData.Tests/API/ApiExtensions.cs

@@ -0,0 +1,43 @@
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.Versioning;
+using System.Threading.Tasks;
+using PublicApiGenerator;
+using VerifyXunit;
+using Xunit;
+
+namespace DynamicData.APITests;
+
+/// <summary>
+/// A helper for doing API approvals.
+/// </summary>
+[ExcludeFromCodeCoverage]
+[UsesVerify]
+public static class ApiExtensions
+{
+    /// <summary>
+    /// Checks to make sure the API is approved.
+    /// </summary>
+    /// <param name="assembly">The assembly that is being checked.</param>
+    /// <param name="namespaces">The namespaces.</param>
+    /// <param name="filePath">The caller file path.</param>
+    /// <returns>
+    /// A Task.
+    /// </returns>
+    public static async Task CheckApproval(this Assembly assembly, string[] namespaces, [CallerFilePath] string filePath = "")
+    {
+        var generatorOptions = new ApiGeneratorOptions { AllowNamespacePrefixes = namespaces };
+        var apiText = assembly.GeneratePublicApi(generatorOptions);
+        var result = await Verifier.Verify(apiText, null, filePath)
+            .UniqueForRuntimeAndVersion()
+            .ScrubEmptyLines()
+            .ScrubLines(l =>
+                l.StartsWith("[assembly: AssemblyVersion(", StringComparison.InvariantCulture) ||
+                l.StartsWith("[assembly: AssemblyFileVersion(", StringComparison.InvariantCulture) ||
+                l.StartsWith("[assembly: AssemblyInformationalVersion(", StringComparison.InvariantCulture) ||
+                l.StartsWith("[assembly: System.Reflection.AssemblyMetadata(", StringComparison.InvariantCulture));
+    }
+}

src/DynamicData.Tests/DynamicData.Tests.csproj

@@ -1,10 +1,10 @@
 <Project Sdk="MSBuild.Sdk.Extras">
   <PropertyGroup>
     <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
-    <NoWarn>$(NoWarn);CS0618;CA1801;CA1063;CS8767;CS8602; CS8618</NoWarn>
+    <NoWarn>$(NoWarn);CS0618;CA1801;CA1063;CS8767;CS8602;CS8618;IDE1006</NoWarn>
     <Nullable>enable</Nullable>
     <LangVersion>latest</LangVersion>
-    <XunitVersion>2.6.1</XunitVersion>
+    <XunitVersion>2.6.2</XunitVersion>
   </PropertyGroup>
 
   <ItemGroup>
@@ -15,7 +15,7 @@
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
     <PackageReference Include="xunit" Version="$(XunitVersion)" />
     <PackageReference Include="xunit.runner.console" Version="$(XunitVersion)" />
-    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.4" />
     <PackageReference Include="Verify.Xunit" Version="22.5.0" />
     <PackageReference Include="FluentAssertions" Version="6.12.0" />
     <PackageReference Include="Microsoft.Reactive.Testing" Version="6.0.0" />

src/DynamicData/Cache/CacheChangeSetEx.cs

@@ -7,13 +7,13 @@ namespace DynamicData.Cache;
 internal static class CacheChangeSetEx
 {
     /// <summary>
+    /// <para>
     /// IChangeSet is flawed because it automatically means allocations when enumerating.
     /// This extension is a crazy hack to cast to the concrete change set which means we no longer allocate
     /// as change set now inherits from List which has allocation free enumerations.
-    ///
-    /// IChangeSet will be removed in a future version and instead <see cref="ChangeSet{TObject, TKey}"/> will be used directly.
-    ///
-    /// In the mean time I am banking that no-one has implemented a custom change set - personally I think it is very unlikely.
+    /// </para>
+    /// <para>IChangeSet will be removed in a future version and instead <see cref="ChangeSet{TObject, TKey}"/> will be used directly.</para>
+    /// <para>In the mean time I am banking that no-one has implemented a custom change set - personally I think it is very unlikely.</para>
     /// </summary>
     /// <typeparam name="TObject">ChangeSet Object Type.</typeparam>
     /// <typeparam name="TKey">ChangeSet Key Type.</typeparam>

src/DynamicData/Cache/Change.cs

@@ -118,16 +118,14 @@ public Change(ChangeReason reason, TKey key, TObject current, Optional<TObject>
     public int CurrentIndex { get; }
 
     /// <summary>
-    /// Gets the previous change.
-    ///
-    /// This is only when Reason==ChangeReason.Replace.
+    /// <para>Gets the previous change.</para>
+    /// <para>This is only when Reason==ChangeReason.Replace.</para>
     /// </summary>
     public Optional<TObject> Previous { get; }
 
     /// <summary>
-    /// Gets the previous change.
-    ///
-    /// This is only when Reason==ChangeReason.Update or ChangeReason.Move.
+    /// <para>Gets the previous change.</para>
+    /// <para>This is only when Reason==ChangeReason.Update or ChangeReason.Move.</para>
     /// </summary>
     public int PreviousIndex { get; }
 

src/DynamicData/Cache/ICache.cs

@@ -6,9 +6,8 @@
 namespace DynamicData;
 
 /// <summary>
-/// A cache which captures all changes which are made to it. These changes are recorded until CaptureChanges() at which point thw changes are cleared.
-///
-/// Used for creating custom operators.
+/// <para>A cache which captures all changes which are made to it. These changes are recorded until CaptureChanges() at which point thw changes are cleared.</para>
+/// <para>Used for creating custom operators.</para>
 /// </summary>
 /// <typeparam name="TObject">The type of the object.</typeparam>
 /// <typeparam name="TKey">The type of the key.</typeparam>

src/DynamicData/Cache/ICacheUpdater.cs

@@ -6,13 +6,13 @@
 namespace DynamicData;
 
 /// <summary>
-/// Api for updating  an intermediate cache
-///
-/// Use edit to produce singular change set.
-///
+/// <para>Api for updating  an intermediate cache.</para>
+/// <para>Use edit to produce singular change set.</para>
+/// <para>
 /// NB:The evaluate method is used to signal to any observing operators
 /// to  reevaluate whether the object still matches downstream operators.
 /// This is primarily targeted to inline object changes such as datetime and calculated fields.
+/// </para>
 ///
 /// </summary>
 /// <typeparam name="TObject">The type of the object.</typeparam>

src/DynamicData/Cache/IChangeSet.cs

@@ -6,9 +6,8 @@
 namespace DynamicData;
 
 /// <summary>
-/// A collection of changes.
-///
-/// Changes are always published in the order.
+/// <para>A collection of changes.</para>
+/// <para>Changes are always published in the order.</para>
 /// </summary>
 /// <typeparam name="TObject">The type of the object.</typeparam>
 /// <typeparam name="TKey">The type of the key.</typeparam>

src/DynamicData/Cache/IIntermediateCache.cs

@@ -6,9 +6,8 @@
 namespace DynamicData;
 
 /// <summary>
-/// An observable cache which exposes an update API.
-///
-/// Intended to be used as a helper for creating custom operators.
+/// <para>An observable cache which exposes an update API.</para>
+/// <para>Intended to be used as a helper for creating custom operators.</para>
 /// </summary>
 /// <typeparam name="TObject">The type of the object.</typeparam>
 /// <typeparam name="TKey">The type of the key.</typeparam>

src/DynamicData/Cache/ISourceUpdater.cs

@@ -6,13 +6,13 @@
 namespace DynamicData;
 
 /// <summary>
-/// API for updating a source cache.
-///
-/// Use edit to produce singular change set.
-///
+/// <para>API for updating a source cache.</para>
+/// <para>Use edit to produce singular change set.</para>
+/// <para>
 /// NB: The evaluate method is used to signal to any observing operators
 /// to reevaluate whether the object still matches downstream operators.
 /// This is primarily targeted to inline object changes such as datetime and calculated fields.
+/// </para>
 ///
 /// </summary>
 /// <typeparam name="TObject">The type of the object.</typeparam>

src/DynamicData/Cache/Internal/IndexCalculator.cs

@@ -5,10 +5,11 @@
 namespace DynamicData.Cache.Internal;
 
 /// <summary>
-/// Calculates a sequential change set.
-///
+/// <para>Calculates a sequential change set.</para>
+/// <para>
 /// This enables the binding infrastructure to simply iterate the change set
 /// and apply indexed changes with no need to apply ant expensive IndexOf() operations.
+/// </para>
 /// </summary>
 /// <remarks>
 /// Initializes a new instance of the <see cref="IndexCalculator{TObject, TKey}"/> class.

src/DynamicData/Cache/ObservableCacheEx.cs

@@ -1139,10 +1139,11 @@ public static IObservable<IChangeSet<TObject, TKey>> DeferUntilLoaded<TObject, T
     }
 
     /// <summary>
-    /// Disposes each item when no longer required.
-    ///
+    /// <para>Disposes each item when no longer required.</para>
+    /// <para>
     /// Individual items are disposed after removal or replacement changes have been sent downstream.
     /// All items previously-published on the stream are disposed after the stream finalizes.
+    /// </para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -2231,9 +2232,8 @@ public static IObservable<IGroupChangeSet<TObject, TKey, TGroupKey>> Group<TObje
     }
 
     /// <summary>
-    /// Groups the source using the property specified by the property selector. Groups are re-applied when the property value changed.
-    ///
-    /// When there are likely to be a large number of group property changes specify a throttle to improve performance.
+    /// <para>Groups the source using the property specified by the property selector. Groups are re-applied when the property value changed.</para>
+    /// <para>When there are likely to be a large number of group property changes specify a throttle to improve performance.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -2262,9 +2262,8 @@ public static IObservable<IGroupChangeSet<TObject, TKey, TGroupKey>> GroupOnProp
     }
 
     /// <summary>
-    /// Groups the source using the property specified by the property selector. Each update produces immutable grouping. Groups are re-applied when the property value changed.
-    ///
-    /// When there are likely to be a large number of group property changes specify a throttle to improve performance.
+    /// <para>Groups the source using the property specified by the property selector. Each update produces immutable grouping. Groups are re-applied when the property value changed.</para>
+    /// <para>When there are likely to be a large number of group property changes specify a throttle to improve performance.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -4153,9 +4152,8 @@ public static void Refresh<TObject, TKey>(this ISourceCache<TObject, TKey> sourc
     }
 
     /// <summary>
-    /// Removes the specified item from the cache.
-    ///
-    /// If the item is not contained in the cache then the operation does nothing.
+    /// <para>Removes the specified item from the cache.</para>
+    /// <para>If the item is not contained in the cache then the operation does nothing.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -4196,9 +4194,8 @@ public static void Remove<TObject, TKey>(this ISourceCache<TObject, TKey> source
     }
 
     /// <summary>
-    /// Removes the specified items from the cache.
-    ///
-    /// Any items not contained in the cache are ignored.
+    /// <para>Removes the specified items from the cache.</para>
+    /// <para>Any items not contained in the cache are ignored.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -4218,9 +4215,8 @@ public static void Remove<TObject, TKey>(this ISourceCache<TObject, TKey> source
     }
 
     /// <summary>
-    /// Removes the specified keys from the cache.
-    ///
-    /// Any keys not contained in the cache are ignored.
+    /// <para>Removes the specified keys from the cache.</para>
+    /// <para>Any keys not contained in the cache are ignored.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -4261,9 +4257,8 @@ public static void Remove<TObject, TKey>(this IIntermediateCache<TObject, TKey>
     }
 
     /// <summary>
-    /// Removes the specified keys from the cache.
-    ///
-    /// Any keys not contained in the cache are ignored.
+    /// <para>Removes the specified keys from the cache.</para>
+    /// <para>Any keys not contained in the cache are ignored.</para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -6110,11 +6105,14 @@ IEnumerable<Change<TObject, TKey>> ReplaceMoves(IChangeSet<TObject, TKey> items)
     }
 
     /// <summary>
+    /// <para>
     /// Produces a boolean observable indicating whether the latest resulting value from all of the specified observables matches
-    /// the equality condition. The observable is re-evaluated whenever
-    ///
+    /// the equality condition. The observable is re-evaluated whenever.
+    /// </para>
+    /// <para>
     /// i) The cache changes
     /// or ii) The inner observable changes.
+    /// </para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>
@@ -6130,11 +6128,14 @@ public static IObservable<bool> TrueForAll<TObject, TKey, TValue>(this IObservab
         where TValue : notnull => source.TrueFor(observableSelector, items => items.All(o => o.LatestValue.HasValue && equalityCondition(o.LatestValue.Value)));
 
     /// <summary>
+    /// <para>
     /// Produces a boolean observable indicating whether the latest resulting value from all of the specified observables matches
-    /// the equality condition. The observable is re-evaluated whenever
-    ///
+    /// the equality condition. The observable is re-evaluated whenever.
+    /// </para>
+    /// <para>
     /// i) The cache changes
     /// or ii) The inner observable changes.
+    /// </para>
     /// </summary>
     /// <typeparam name="TObject">The type of the object.</typeparam>
     /// <typeparam name="TKey">The type of the key.</typeparam>

src/DynamicData/Kernel/InternalEx.cs

@@ -68,11 +68,9 @@ public static IDisposable ScheduleRecurringAction(this IScheduler scheduler, Tim
     /// Schedules a recurring action.
     /// </summary>
     /// <remarks>
-    ///  I took this from
-    ///
-    /// https://www.zerobugbuild.com/?p=259
-    ///
-    /// and adapted it to receive.
+    /// <para> I took this from.</para>
+    /// <para>https://www.zerobugbuild.com/?p=259.</para>
+    /// <para>and adapted it to receive.</para>
     /// </remarks>
     /// <param name="scheduler">The scheduler.</param>
     /// <param name="interval">The interval.</param>