Merge pull request #1098 from akarnokd/IAEMethodDocs_1128

Add documentation to AsyncEnumerable methods.

Ix.NET/Source/System.Linq.Async/System.Linq.Async.csproj

@@ -23,8 +23,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Condition="'$(TargetFramework)' != 'netcoreapp3.0' and '$(TargetFramework)' != 'netstandard2.1' " 
-                      Include="Microsoft.Bcl.AsyncInterfaces" Version="1.0.0" />
+    <PackageReference Condition="'$(TargetFramework)' != 'netcoreapp3.0' and '$(TargetFramework)' != 'netstandard2.1' " Include="Microsoft.Bcl.AsyncInterfaces" Version="1.0.0" />
     <ReferenceAssemblyProjectReference Include="..\refs\System.Linq.Async.Ref\System.Linq.Async.Ref.csproj" />
   </ItemGroup>
 

Ix.NET/Source/System.Linq.Async/System/Linq/IOrderedAsyncEnumerable.cs

@@ -8,12 +8,41 @@
 
 namespace System.Linq
 {
+    /// <summary>
+    /// Represents a sorted async-enumerable sequence.
+    /// </summary>
+    /// <typeparam name="TElement">The type of the elements of the sequence.</typeparam>
     public interface IOrderedAsyncEnumerable<out TElement> : IAsyncEnumerable<TElement>
     {
+        /// <summary>
+        /// Performs a subsequent ordering on the elements of an ordered async-enumerable according to a key.
+        /// </summary>
+        /// <typeparam name="TKey">The type of the key produced by keySelector.</typeparam>
+        /// <param name="keySelector">The function used to extract the key for each element.</param>
+        /// <param name="comparer">The comparer used to compare keys for placement in the returned sequence.</param>
+        /// <param name="descending">true to sort the elements in descending order; false to sort the elements in ascending order.</param>
+        /// <returns>An ordered async-enumerable whose elements are sorted according to a key.</returns>
         IOrderedAsyncEnumerable<TElement> CreateOrderedEnumerable<TKey>(Func<TElement, TKey> keySelector, IComparer<TKey>? comparer, bool descending);
+
+        /// <summary>
+        /// Performs a subsequent ordering on the elements of an ordered async-enumerable according to a key provided via a ValueTask.
+        /// </summary>
+        /// <typeparam name="TKey">The type of the key produced by keySelector.</typeparam>
+        /// <param name="keySelector">The function used to extract the key for each element as a ValueTask.</param>
+        /// <param name="comparer">The comparer used to compare keys for placement in the returned sequence.</param>
+        /// <param name="descending">true to sort the elements in descending order; false to sort the elements in ascending order.</param>
+        /// <returns>An ordered async-enumerable whose elements are sorted according to a key.</returns>
         IOrderedAsyncEnumerable<TElement> CreateOrderedEnumerable<TKey>(Func<TElement, ValueTask<TKey>> keySelector, IComparer<TKey>? comparer, bool descending);
 
 #if !NO_DEEP_CANCELLATION
+        /// <summary>
+        /// Performs a subsequent ordering on the elements of an ordered async-enumerable according to a key provided via a ValueTask.
+        /// </summary>
+        /// <typeparam name="TKey">The type of the key produced by keySelector.</typeparam>
+        /// <param name="keySelector">The function used to extract the key for each element as a ValueTask supporting cancellation.</param>
+        /// <param name="comparer">The comparer used to compare keys for placement in the returned sequence.</param>
+        /// <param name="descending">true to sort the elements in descending order; false to sort the elements in ascending order.</param>
+        /// <returns>An ordered async-enumerable whose elements are sorted according to a key.</returns>
         IOrderedAsyncEnumerable<TElement> CreateOrderedEnumerable<TKey>(Func<TElement, CancellationToken, ValueTask<TKey>> keySelector, IComparer<TKey>? comparer, bool descending);
 #endif
     }

Ix.NET/Source/System.Linq.Async/System/Linq/Operators/Aggregate.cs

@@ -10,6 +10,18 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerable
     {
+        /// <summary>
+        /// Applies an accumulator function over an async-enumerable sequence, returning the result of the aggregation as a single element in the result sequence.
+        /// For aggregation behavior with incremental intermediate results, see System.Interactive.Async.AsyncEnumerableEx.Scan{TSource}.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence and the result of the aggregation.</typeparam>
+        /// <param name="source">An async-enumerable sequence to aggregate over.</param>
+        /// <param name="accumulator">An accumulator function to be invoked on each element.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element with the final accumulator value.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="accumulator"/> is null.</exception>
+        /// <exception cref="InvalidOperationException">(Asynchronous) The source sequence is empty.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<TSource> AggregateAsync<TSource>(this IAsyncEnumerable<TSource> source, Func<TSource, TSource, TSource> accumulator, CancellationToken cancellationToken = default)
         {
             if (source == null)
@@ -99,6 +111,19 @@ static async ValueTask<TSource> Core(IAsyncEnumerable<TSource> source, Func<TSou
         }
 #endif
 
+        /// <summary>
+        /// Applies an accumulator function over an async-enumerable sequence, returning the result of the aggregation as a single element in the result sequence. The specified seed value is used as the initial accumulator value.
+        /// For aggregation behavior with incremental intermediate results, see System.Interactive.Async.AsyncEnumerableEx.Scan{TSource, Accumulate}".
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <typeparam name="TAccumulate">The type of the result of the aggregation.</typeparam>
+        /// <param name="source">An async-enumerable sequence to aggregate over.</param>
+        /// <param name="seed">The initial accumulator value.</param>
+        /// <param name="accumulator">An accumulator function to be invoked on each element.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element with the final accumulator value.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="accumulator"/> is null.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<TAccumulate> AggregateAsync<TSource, TAccumulate>(this IAsyncEnumerable<TSource> source, TAccumulate seed, Func<TAccumulate, TSource, TAccumulate> accumulator, CancellationToken cancellationToken = default)
         {
             if (source == null)
@@ -167,6 +192,21 @@ await foreach (var item in source.WithCancellation(cancellationToken).ConfigureA
         }
 #endif
 
+        /// <summary>
+        /// Applies an accumulator function over an async-enumerable sequence, returning the result of the aggregation as a single element in the result sequence. The specified seed value is used as the initial accumulator value,
+        /// and the specified result selector function is used to select the result value.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <typeparam name="TAccumulate">The type of the accumulator value.</typeparam>
+        /// <typeparam name="TResult">The type of the resulting value.</typeparam>
+        /// <param name="source">An async-enumerable sequence to aggregate over.</param>
+        /// <param name="seed">The initial accumulator value.</param>
+        /// <param name="accumulator">An accumulator function to be invoked on each element.</param>
+        /// <param name="resultSelector">A function to transform the final accumulator value into the result value.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element with the final accumulator value.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="accumulator"/> or <paramref name="resultSelector"/> is null.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<TResult> AggregateAsync<TSource, TAccumulate, TResult>(this IAsyncEnumerable<TSource> source, TAccumulate seed, Func<TAccumulate, TSource, TAccumulate> accumulator, Func<TAccumulate, TResult> resultSelector, CancellationToken cancellationToken = default)
         {
             if (source == null)

Ix.NET/Source/System.Linq.Async/System/Linq/Operators/All.cs

@@ -10,6 +10,16 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerable
     {
+        /// <summary>
+        /// Determines whether all elements of an async-enumerable sequence satisfy a condition.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">An async-enumerable sequence whose elements to apply the predicate to.</param>
+        /// <param name="predicate">A function to test each element for a condition.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element determining whether all elements in the source sequence pass the test in the specified predicate.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="predicate"/> is null.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<bool> AllAsync<TSource>(this IAsyncEnumerable<TSource> source, Func<TSource, bool> predicate, CancellationToken cancellationToken = default)
         {
             if (source == null)

Ix.NET/Source/System.Linq.Async/System/Linq/Operators/Any.cs

@@ -10,6 +10,15 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerable
     {
+        /// <summary>
+        /// Determines whether an async-enumerable sequence contains any elements.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">An async-enumerable sequence to check for non-emptiness.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element determining whether the source sequence contains any elements.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<bool> AnyAsync<TSource>(this IAsyncEnumerable<TSource> source, CancellationToken cancellationToken = default)
         {
             if (source == null)
@@ -25,6 +34,16 @@ static async ValueTask<bool> Core(IAsyncEnumerable<TSource> source, Cancellation
             }
         }
 
+        /// <summary>
+        /// Determines whether any element of an async-enumerable sequence satisfies a condition.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">An async-enumerable sequence whose elements to apply the predicate to.</param>
+        /// <param name="predicate">A function to test each element for a condition.</param>
+        /// <param name="cancellationToken">The optional cancellation token to be used for cancelling the sequence at any time.</param>
+        /// <returns>An async-enumerable sequence containing a single element determining whether any elements in the source sequence pass the test in the specified predicate.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="predicate"/> is null.</exception>
+        /// <remarks>The return type of this operator differs from the corresponding operator on IEnumerable in order to retain asynchronous behavior.</remarks>
         public static ValueTask<bool> AnyAsync<TSource>(this IAsyncEnumerable<TSource> source, Func<TSource, bool> predicate, CancellationToken cancellationToken = default)
         {
             if (source == null)

Ix.NET/Source/System.Linq.Async/System/Linq/Operators/AppendPrepend.cs

@@ -12,6 +12,14 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerable
     {
+        /// <summary>
+        /// Append a value to an async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">Source sequence to append the value to.</param>
+        /// <param name="element">Element to append to the specified sequence.</param>
+        /// <returns>The source sequence appended with the specified value.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Append<TSource>(this IAsyncEnumerable<TSource> source, TSource element)
         {
             if (source == null)
@@ -25,6 +33,14 @@ public static IAsyncEnumerable<TSource> Append<TSource>(this IAsyncEnumerable<TS
             return new AppendPrepend1AsyncIterator<TSource>(source, element, appending: true);
         }
 
+        /// <summary>
+        /// Prepend a value to an async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">Source sequence to prepend the value to.</param>
+        /// <param name="element">Element to prepend to the specified sequence.</param>
+        /// <returns>The source sequence prepended with the specified value.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Prepend<TSource>(this IAsyncEnumerable<TSource> source, TSource element)
         {
             if (source == null)

Ix.NET/Source/System.Linq.Async/System/Linq/Operators/AsAsyncEnumerable.cs

@@ -10,6 +10,13 @@ public static partial class AsyncEnumerable
     {
         // NB: Synchronous LINQ to Objects doesn't hide the implementation of the source either.
 
+        /// <summary>
+        /// Hides the identity of an async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
+        /// <param name="source">An async-enumerable sequence whose identity to hide.</param>
+        /// <returns>An async-enumerable sequence that hides the identity of the source sequence.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
         public static IAsyncEnumerable<TSource> AsAsyncEnumerable<TSource>(this IAsyncEnumerable<TSource> source) => source;
     }
 }